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Preface 



This book is meant to be a "cookbook" of Level II BASIC rou- 
tines for the Radio Shack TRS-80 Model I Computer. If you have 
questions about the ways in which you can output graphics to the 
display. Programming Techniques for Level 11 BASIC can help you 
out. If you want to know about efficient sorting and searching, this 
book will show you how. If you want some concrete examples of 
how to interface to machine-language routines in BASIC, you can 
find the information and examiDles here. Programming Techniques 
for Level II BASIC is meant to supplement the Level II BASIC 
Reference Manual; it provides practical examples of common BA- 
SIC operations that you will want to try. 

What do you need to know before using this book? You should 
have at least a nodding acquaintance with Level II BASIC, You 
should be somewhat familiar with simple BASIC program structure 
and Level II BASIC operations. But, if you don't know all of the 
details in Level II, don't be afraid to plunge right into the exam- 
ples in this book. The best way to learn is by practical example, 
and we have attempted to provide plenty of them. You don't need 
a degree in computer science or mathematics, either. Most opera- 
tions described here use simple straightforward logic; Level II 
BASIC is capable of providing advanced mathematical processing, 
but we have kept math discussion to an absolute minimum. 

Most of all, you need to have an interest in using the power of 
TRS-80 Level II BASIC. We all have a tendency to become jaded 
as we are exposed to better and better small computer systems, but 
the BASIC operations provided in Level II are extremely powerful. 
This book will show you how to use them, whether your goal is 



accounting, games, inventory, programmed instruction, ham radio, 
self-education, or almost any other application. 

Chapter 1 provides a revievi^ of Level II BASIC statements and 
commands. We'll discuss the four modes of Level II— command, 
execution, edit, and monitor— and the commands associated with 
each. 

Chapter 2 discusses the types of variables provided in Level II 
BASIC, binary representation, and logical functions. 

"Strings and Things" are discussed in Chapter 3. String formats, 
ASCII data, string operations, cursor control, and text editing are 
a few of the subjects presented. 

Display of reports, columnating data, PRINT USING, line 
printer format, and other topics related to displaying or printing 
data in alphanumeric form are covered' in Chapter 4. 

Chapter 5 discusses the approaches to displaying graphics data 
on the TRS-80 video screen. Well describe four techniques that 
range from display of graphs to high-speed animation. 

"Tables, Chessboards, and the Fourth Dimension" (Chapter 6) 
discusses lists, tables, arrays, and other ways to organize data 
within BASIC programs. 

One of the most critical areas in BASIC programming is that 
of searching and sorting data. Chapter 7 discusses the various 
methods that can be used to perform these functions. 

Chapter 8 describes the built-in precision, numeric, random 
number, and trigonometric functions available in Level II BASIC. 

Cassette tape operations are discussed in Chapter 9. Tape for- 
mats and methods for "blocking" data are described, along with 
file operations. 

Chapter 10 discusses general problems in "debugging" BASIC 
programs, the error functions in BASIC, and error processing. 

Level II BASIC has the ability to interface to assembly-language 
coding; Chapter 11 describes how you can do this to utilize the 
high speed of assembly language for operations that must be 
very efficient. 

The last chapter describes the structure of Level II BASIC in 
regard to ROM subroutines, tokens, variable storage, and other "in- 
ternals" that are not normally available to the BASIC programmer. 



William Babden, Jr. 



To Gaga and Steve 



Contents 



CHAPTER 1 



A Good BASIC Foundation 



I'd Like to Make a Statement — Program Flow — Pick a Statement, 
Any Statement — Number Crunchies, the New Computer Energy 
Food — Command Performance — Editors Are Not So Hard Bitten 
After All 



CHAPTER 2 

To Be Precise 27 

A Long Time Ago in a Computer System Far, Far Away — Integer 
Variables — Murphy's Rule Number 32K — Single-Precision Vari- 
ables — Double or Nothing — A Treatise on the Use of Numbers 
Great and Small With Special Reference to the TRS-80 - Once 
More Unto the Breach 



CHAPTER 3 

Strings and Things 43 

ASCII Strings — From One to Hundreds — String Operations: 
Comparison and Concatenation — Printing the Unprintable — Left, 
Right, Left, Right, Mid, Right ... - The STRING-? String - Nu- 
meric to Strings and Back Again — A Thousand Cursors Upon You, 
EfFendi! — The Universal Gee Whiz Input — Text Editing — Another 
Approach 



CHAPTER 4 
Our Latest Report Indicates 62 

One From Column A and One From Column B — There's No Justi- 
fication for This ... - Dollars and Cents - $4.50 for a Slice of 
Cheesecake? - All tlie Data That's Fit to Print (And Some That 
Isn't ) 

CHAPTER 5 

Graphic Examples 78 

Back to the Books ... - SETting Good Examples - Plotting Along 
With SET/RESET - Guns Versus Butter - A Moving Experience 

- Good Points to Consider - The POKE Graphics Method - String 
Graphics and the Chattanooga TRS-80 — String Graphics Using 
Dummy Strings — Graphics Review — Plow to Draw a Straight Line 

CHAPTER 6 

Tables, Chessboards, and the Fourth Dimension .... 99 

BASIC DATA Lists - READs and RESTORES - Mixing It Up - 
Array of Hope — One-Dimensional Arrays — Look It Up in the 
Index — Tables and the Boarding House Reach — Two Dimensions 
and Beyond — Initializing Arrays 

CHAPTER 7 

The Search for Better Data and Sorting It All Out . . 121 

Unordered Data: No Order at All — Ordered Lists — The Binary 
S"arch Myste'y — Algorithms of a Different Sort — Rising Witli 
the Tide — The (New) Shell Game — Toward a Faster Sort — 
Mergers Are B.g Busmess 

CHAPTER 8 

The TRS-80 Functions Perfectly 142 

What? More Precision Operations? — Are You Good at Fractions? 

— A Sign Function: Absolutely! — Pick a Number, Any Number — 
Trigonometric (Say What?) Functions 

CHAPTER 9 

How TO Get It All on Tape 160 

Tape Commands — Follow tlie Leader — Why Is There a Question 
Mark After CLOAD?? - Wliat's That (Blinking) Asterisk? - Using 
PRINT# and INPUT# - Space, Speed, and (S}Packing - Se- 
quential Cassette Files — Two Cassettes Are Better Than One 



CHAPTER 10 

To Err Is Human 171 

Unprintable Errors and Other Types — Trapping the Wild Error — 
Error Processing — Simulating Errors — Debugging 

CHAPTER 11 

Son of BASIC Meets the Machine Code Monster . . . 184 
Hello, Mr. Chips - TRS-80 Memory Layout - SYSTEM Tapes - 
Using the USR(O) Call - Any Arguments? - Getting an Argument 
Back — Handling Two-Way Passing and Multiple Arguments — 
Handling Multiple Machine-Language Subroutines - A Neat 
Method for Embedding Machine-Language Subroutines in BASIC 
Code 

CHAPTER 12 

FOKEiNG Around m Memory 204 

An Approach to PEEKing - BASIC Statement Format - The Search 
for Variables - Houston, We're Going to Change the DCBs on Our 
TRS-80 Before the EVA ... — Keyboard Kapers — Cassette Opera- 
tions — Further Investigation Shows . . . 

Index 221 



CHAPTER 1 



A Good BASIC Foundation 



This book is applications oriented. It is not meant to be a refer- 
ence manual-the Level II BASIC Reference Manual is ideal for 
that. Here's what Programming Techniques for Level 11 BASIC will 
do for you: 

® Provide further explanation of how Level II Commands op- 
erate in practical applications 
® Show you various approaches to solving appMcations problems 

such as searching for data, high-speed graphics, and string 

manipulation 
® Give some insight into the "internals" of Level II BASIC so 

you can speed up your programs and make them more eflS- 

cient 
® Reveal some useful programming tricks for Level II BASIC, 

such as assembly-language embedded in BASIC strings and 

repeat keys for keyboard input 

The book is meant to be both a tutorial manual and a collection 
of modules; you can sit down and read it straight through (we are 
in no way assuming Hability for optical damage for this feat) or 
you can leave it on the shelf and refer to it for various appHcations 
problems as they crop up. 

All right ... Do you have the TRS-80 plugged in and warmed 
up? Have you sandpapered your finger tips for optimizing your key- 
board input? 

In this chapter we'll present some BASIC basics. Feel free to 
skip the chapter if you're well-versed in aspects of Level II BA- 
SIC . . . such as program flow, statement types, variables, and the 
Editor. (We will, however, have an armed guard who will peri- 




Au. YOU BASIC li£AD£llS HAVE BEEht FOfl£h/AM£l>... hJOW I WANT TO 
HBAR SOME hllCH-LBV£L BASIC LAH&UAGB ...THIS IS A T£St// " 

odically be visiting our readers and testing them on the aspects 
of BASIC applications. Forewarned is forearmed. . . .) 

I'd Like to Make a Statement 

All BASIC programs are made up of BASIC lines that contain 
statements. A statement is simply a command that tells the TRS-80 
to perform some action in the high-level BASIC language. A BA- 
SIC interpreter translates each BASIC statement into instructions 
that the Z-80 microprocessor in the TRS-80 can understand. One 
BASIC statement may generate hundreds of Z-80 machine-lan- 
guage instructions. Since the machine-language instructions oper- 
ate in millionths of a second, each BASIC statement is interpreted 
by the BASIC interpreter very rapidly. 

Every BASIC statement line has a statement number. These are 
assigned by the programmer (that's you) and may be any number 
from to 65529. The remainder of the statement line has text that 
defines the BASIC statements in the statement line. A typical pro- 
gram is shown below. This program asks for your name and then 
prints a greeting and a question. 

COMMENTS 

100 INPUT "NAME »!A» 'input name 

200 PRINT "HI "iA» 'greeting 

300 INPUT "ARE YOU ENJOYINS THIS BOOK" iB4 '•!UerY 

400 IF B$<>"YES" SOTO 300 '9o if not res 

500 PRINT "THAT'S FINEi ";A» 'proper- response 
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This program shows the power of the computer in altering pub- 
lic opinion, as it will not accept no for an answer. (Programs such 
as this have been instrumental in creating survey data for the au- 
thor's book promotions.) 

There are five BASIC statement Mnes in this short program. Pro- 
gram execution starts at line number 100 where the BASIC state- 
ment INPUT "NAME ";A$ is encountered. The BASIC interpreter, 
which is a machine-language program in ROM (Read-Only-Mem- 
ory) translates the "INPUT" statement into a display of NAME? 
and then waits for you to type in your name. 

After you type your name and press "ENTER", the string of 
characters making up the name is assigned the variable name A$. 
Future references to A$ will refer to that string of characters. 

The next statement line executed is line 200, which displays 
"HI " followed by your name (variable A$). 

Next, line 300 causes the BASIC interpreter to print "ARE YOU 
ENJOYING THIS BOOK?" and wait for the answer. You then type 
"YES", "NO", "SOMEWHAT", or another string of characters fol- 
lowed by "ENTER". This string of characters is assigned the 
name B$. 

Next, statement 400 tests the string of characters (variable B$) 
to see if it is "YES". If it is not ( <> ), the program GOes TO state- 
ment line 300 again where the question is again typed and waits 
for your response; if the answer is "YES", statement line 500 prints 
"THAT'S FINE, " followed by your name. 

Program Flow 

This short program illustrates some important aspects about 
BASIC (and many other programming languages). Programs flow 
from beginning to end with each statement line numbered in as- 
cending order (200 follows 100, 300 follows 200, and so forth). 
Program flow may be altered by testing conditions within the pro- 
gram. The program tested for the "YES" response and altered the 
flow either back to statement line 300 or allowed the program to 
"drop through" to line 500. In a typical program, there may be 
dozens of these tests, and the program paths will be altered accord- 
ing to the results of the tests to create a type of tree structure shown 
in Figure 1-1. 

Let's discuss the statement format again. The line numbers in 
the above program are in increments of 100. They could just as 
well have been any ascending sequence of numbers such as 101 102 
222, 535, 65500 or 110, 120, 130, 140, 150. A common technique is 
to use increments of 10 (110, 120, 130, and so forth). Statement 
lines are then added between existing statement lines by entering 
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Figure 1-1. Program tree structure. 

a new line with a number that is in sequence between the two ex- 
isting statement numbers. If we want to add a new statement be- 
tween 200 and 300, for example, we could type 

250 PRINT "I'M A LIBRA" 'trs-SO must be an astrology nut 

Statement line 250 would then appear- between 200 and 300. 

The remainder of the statement lines are the text of the state- 
ments. As you know from reading the Level II BASIC Reference 
Manual {What? Guard . . .), multiple statements may be put into 
one line. We could say 

100 INPUT "NAME ";A$:PR1NT "HI ";A$ 

in place of statement lines 100 and 200 above, for example. The 
colon ( : ) marks the beginning of a new statement. The advantages 
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of this format are that it saves space in memory (data associated 
with the hne number takes up four bytes of RAM memory) and 
it saves time (each new statement line is referenced by the preced- 
ing line and must be found in a list of statement lines). The dis- 
advantage is that crowded lines make a program very difficult to 
read or follow. This code 

1035 I=7:NEXT:GOTO1037ELSENEXT:PRINTCHR*(B)!:G<-iTO103a ' ■ ' "t^"" 

1B37 IF M>lANDF=0ANDM<>7THENSOSUB95a0:IF!N$=»a"THEN10Ba 

is almost incomprehensible to anyone not skilled in codes and ci- 
phers. To avoid confusing you, we'll be using single statement lines 
in our code, with blanks and remarks. The code below shows this 
technique. The brackets indicate levels of loops (we'll cover this 
aspect of coding shortly); the single quote marks the beginning of 
a comment. Most of our lines will be commented to help you fol- 
low the program flow. When you enter the programs, disregard re- 
marks, since they will slow down the programs and create some 
differences between measured times in the book and actual times. 
(The effect of using a quote for a comment is to actually create a 
new statement of the form :REM!) You can also leave out blanks 



1000 PRINT CHR*(28);CHR3i(31): 

1100 PRINT CHRS<28):CHR*(14)! 

1200 H=63 

1300 V=14 

1400 FOR 1=1 TO H 

1500 PRINT CHR$<2S) ; 

1600 NEXT I 

1700 FOR 1=1 TO V 

1800 PRINT CHR«<26) : 

1900 NEXT I 

2000 V=V-1 

2100 H=H-1 

2200 FOR 1=1 TO H 

2300 PRINT CHR$(24) ; 

2400 NEXT I 

2500 FOR 1=1 TO V 

2600 PRINT CHR3i(27>; 

2700 NEXT I 

2800 V=V-1 

290B H=H-1 

3000 SOTO 1400 



REMARKS: DO 
NOT ENTER 

I II ■* .1 



OUTER 
LOOP 



/ 



home and clear screen 
home and turn on cursor 
initial horizontal 
initial vertical 
upper 

move to right 
loop 

side 
move dcTS 
"- • loop 

adjust vertical 
adjust horizontal 
r 'bottom 

m o ve__:t<r'T^ f t 

op 
left side 
move UP 
•- • loop 

adjust vertical 
adjust horizontal 
'-'loop for next spiral 




INNER 
LOOPS 



Pick a Statement, Any Statement 

Now that we know the statement line format, the only other thing 
required to construct a program is to choose the right combinations 
of statement types. Not as easy as it sounds, is it? However, to help 
in this task we've attempted to categorize all of the Level II BASIC 
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statement types in one table called Level II BASIC Statements and 
Commands (Table 1-1). Let's go through the basic categories for 

review. ,1, j- 

BRANCHes alter the sequence of a program by either a condi- 
tional or unconditional branch. GOTO 100 will unconditionally 

transfer control to statement 100. Conditional branches transfer 
control if the conditions are met; otherwise, the next statement line 
in sequence is interpreted. 

There is one type of unconditional branch in Level II BASIC, the 
GOTO. It transfers control to the named statement number 

TOO GOTO 200 'unconditionally jump to line 200 

There are four types of conditional branches. IF . . . THEN (line 
number) transfers control to a statement if the condition before the 
THEN is met. 

100 IF A=1 THEN 200 'jump if A=l 

200 IF A$ = "ED" THEN 300 'jump if A$ = "ED" 

The first THEN above transfers control to statement line 200 if 
variable A is equal to 1. The second THEN transfers control to 
statement line 300 if the string variable A$ is equal to "ED". 

The second type of conditional branch is the IF . . . THEN ac- 
tion, such as 

200 IF A=1.23 THEN PRINT "1.23" 'print value if 1.23 

The third type of conditional branch is the IF . . . THEN . . . 
ELSE. This may transfer control to another statement line as in 

100 IF A = THEN 200 ELSE 300 'jump to 200 if A = 

'otherwise jump to 300 

or it may cause other actions as in 

100 IF A = THEN PRINT "0" ELSE PRINT 'print "0" or "NOT 0" 

"NOT 0" 

which prints "0" if variable A equals or "NOT 0" if variable A 
does not equal 0. 

The last type of conditional branch is ON . . . GOTO. . . . This 
statement type transfers control to a specified line number accord- 
ing to the condition before the GOTO. 

100 ON A GOTO 100,200,300 'jump to 100 if A = 1, 200 

'if A=2, 300 if A = 3, next 
'line if none 

The above example will transfer control to line 100 if variable A 
is equal to 1, line 200 if A is 2, line 300 if A is 3, or will not branch 
if A is other than 1, 2, or 3. 

Another type of statement diat alters the flow of BASIC programs 
is the subroutine-type statement. A subroutine is a conveniently 
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Table 1-1. Level H BASIC Statements and Commands 



LEVEL II BASIC STATEMENTS 




Branches 




GOTOn 


Branch to line n 


IF : THEN n 


Conditional branch 


IF : THEN . . 


Conditional action 


IF : THEN : ELSE . . 




ON : GOTO l.m.n, . . . 


Computed GOTO 


Catcette Tape 




INPUT #-1, list 


Read list 


PRINT #-1, list 


Write list 


Commands 




AUTO n,v 


Auto line # at n with v increments 


CLEAR k 


Clear k bytes 


CLOAD "string" 


Load cassette file "string" 


CLOAD? "string" 


Check file "string" 


CONT 


Continue 


CSAVE "string" 


Write cassette file "string" 


DELETE l-m 


Delete lines 1 thru m 


EDIT n 


Invoke EDIT mode for line n 


LIST l-m 


List lines 1 thru m 


NEW 


Clear program 


RUN n 


Begin execution at line n 


SYSTEM 


Invoke MONITOR mode 


TROFF 


Turn off trace 


TRON 


Turn on trace 


Data Tables and Arrays 




DATA list 


Establish data table 


DIAA name (diml,dim2, . . .dimk) 


Establish array 


READ list 


Read from data 


RESTORE 


Reset data pointer 


Define Variable Type 




DEFDBL letter range 


Double precision 


DEFINT letter range 


Integer 


DEFSNG letter range 


Single precision 


DEFSTR letter range 


String 


Error Functions 




ERL 


Get error line # 


ERR/2 + 1 


Get error code 


ERROR code 


Simulate error 


ON ERROR GOTO n 


Error trap 


RESUME n 


Resume execution 


Functions 




ABS(e) 


Absolute value 


ATN(e) 


Arc tangent 


CDBL(e) 


Double precision 


CINT{e) 


Integer (small) 


COS(e) 


Cosine 


CSNG(e) 


Single precision 
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Table 1-1 cont. Level II BASIC Statements and Commands 



Functions — cont, 

EXP(e) 

FIX{e) 

INT(e) 

LOG(e) 

RANDOM 

RND(e) 

SGN(ej 

SIN(e) 

SQR(e) 

TAN(e) 

Graphics 

CLS 

P01NT(x,y) 

POS(O) 

RESET(x,y) 

SET(x,y) 

Input 

INPUT list 

INPUT "string";list 

INP(port) 

INKEY$ 

Loop Control 

FOR name = e TO e STEPe 
NEXT name 

Machlns Language 

PEEK(address) 
POKE address, V 
USR(O) 
VARPTR(variable) 

Miscallaneous 

END 

LETe = e 
AAEM 
REM 
STOP 



Operators 

t 

AND,OR,NOT 

+ 

Output 

OUT port.v 

Printing 

PRINT list 
PRINT TAB(k). . 
PRINT @. . . 



Natural exponential 
Truncation 
Integer (large) 
Natural log 
Reseed generator 
Pseudo-random # 
Sign (-1,0, + !) 
Sine 

Square root 
Tangent 

Clear screen 

Get - 1 if on, if off 

Get cursor position 

Clear point 

Set point 

Input list of items 
Print & input 
Input value of port 
Get one-char string 

Define loop 

Continue and terminate loop 

Get value at address 
Store V in address 
Call subroutine 
Get address of variable 

End execution 

Assignment 

Get # of unused bytes 

Remark 

Stop execution (break) 

Multiple statements/In 

Arithmetic 

Exponentiation 

Relational and string 

Logical 

String concatenation 

Output V to port 

Print list of items 

Tab 

Print at 
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Table 1-1 cont. Level II BASIC Statements and Commands 



Printing — cont. 

PRINT USING $, 



ist 



String 

ASC("string") 

CHR${e) 

FRE($} 

LEN{$) 

LEFT${$,v) 

MID$($,p,v) 

RIGHT$($,v) 

STR$(e) 

STRING$(v,"char") 

VAL("string") 

Subroutines 

GOSUB n 

ON e GOSUB l.m.n, . . , 

RETURN 

Variables 

A-Z 

Ax-Zx where x is A-Z or 0-9 

$ 

% 

1 

# 

D 



Key: 



n 

k,v,w 

"string" 

l-m 

list 

name 

letter range 

(x,y) 

$ 

"char" 

e 

l,m,n, . . . 



Formatted print 

No tab 

Tab 

Get ASCII code 
Gat one-character string 
Get amount of space 
Get length of string 
Get first v characters 
Get length v, start p 
Return lost v characters 
Convert numeric to string 
Get string of v chr 
Convert string to num 

Subroutine call 
Computed subroutine call 
Subroutine return 



String suffix 
Integer suffix 
Single-precision suffix 
Double-precision suffix 
Scientific notation suffix 

(double precision) 
Scientific notation suffix 

(single precision) 

Relational expression 

Line number 

Other action or n 

Constant 

Text string 

Lines l-m 

Item list 

Var name 

Initial letter from a-d,e 

Graphics x=0 to 127, y = to 47 or e 

String variable 

]-chr str 

Expression, variable, or constant 

Line numbers 



LEVEL II BASIC MONITOR MODE (SYSTEM) 



SYSTEM 
*? name 
*?/address 
*?/ 



Invokes monitor mode 
Loads object file "name" 
Execute at address (dec) 
Execute at default addr 
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Table 1-1 cont. Level 11 BASIC Statements and Commands 



LEVEL II BASIC EDIT MODE 




EDITn 




Enter EDIT mode for line n 


A 




Cancel changes already made 


nC 




Change n characters 


nD 




Delete n characters to right 


E 




End edit, save changes 


H 
1 




Delete remainder of line & 1 
Insert 


nKc 




Delete all characters till nth 
occurrence of character c 


L 




List remainder of line 


Q 




End edit and cancel all chngs 


nSc 




Search for nth occurrence of c 


X 




Display remainder, move end 


n*- 




Backspace n spaces 


shiftt 




Escape from edit subcommand 


nspace 




Move n characters to right 


LEVEL II 


BASIC ERROR CODES 




BS 


9 


Subscript out of range 


CN 


17 


Can't continue 


DD 


10 


Redimensioned array 


FC 


5 


Illegal function call 


FD 


22 


Bad file data 


ID 


12 


Illegal direct 


13 


23 


Disk BASIC 


LS 


15 


String too long 


AAO 


21 


Missing operand 


NF 


1 


NEXT without FOR 


NR 


18 


No RESUME 


OD 


4 


Out of data 


OM 


7 


Out of memory 


OS 


14 


Out of string space 


OV 


6 


Overflow 


RG 


3 


Return without GOSUB 


RW 


19 


RESUME without error 


SN 


2 


Syntax error 


ST 


16 


String formula too complex 


TAA 


13 


Type mismatch 


UE 


20 


Unprintable error 


UL 


8 


Undefined line 


/O 


11 


Division by zero 



grouped set of from 1 to hundreds of BASIC statements. A call is 
made to a subroutine by a GOSUB statement, as in 

100 A=l 'set A to 1 

200 GOSUB 10000 'go to subroutine 

300 B=A 'new value of A from subroutine 

which transfers control to statement number 10000. The GOSUB's 
action is identical to a GOTO except that the return point of 300 is 
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recorded by the BASIC interpreter. At the end of the subroutine a 
RETURN statement causes a return to the statement following the 
GOSUB. Let's see how this works. Suppose that we have a subrou- 
tine to skip 3 lines. 



100 PRINT "LINE 1" 'now on line 1 
200 GOSUB 1000 'skip 3 lines 

300 PRINT "LINE 5" 'now on line 5 



1000 PRINT 'skip line 

1010 PRINT 'skip line 

1020 PRINT 'skip line 

1030 RETURN 'return after GOSUB 



(The squiggly line in the above code does not mean the artist is 
nervous. It stands for other BASIC code that has been left out.) 
First statement 100 is executed. Next, the "GOSUB 1000" causes the 
four lines of subroutine 1000 to be executed. The last line returns 
control to statement 300. 

Subroutines are generally used to save memory. If, for example, a 
program needs to skip three lines in a number of places, it would 
make sense to have the code for skipping three lines at one spot 
rather than dozens of places in the program. 

The statement type ON . . . GOSUB operates exactly the same 
as the ON . . . GOTO except that control is returned to the state- 
ment following the one calling the subroutine. 

Loops in BASIC allow a program to repeat operations, rather 
than coding the operations as a long repetitious list of BASIC state- 
ments. Suppose, for example, that it is necessary to fill the video 
display with asterisks. One way to do this would be to print an 
asterisk 1024 times, one for each video display position. 



100 


PRINT 


"*" , 


'print "*" at current 
'location 


200 


PRINT 


"i<tl. 


'another 


300 


PRINT 
etc. 


"*"• 


'and another and another . . . 



An easier way would be to create a loop of 1024 repetitions that 
would accompHsh the action in a very short piece of BASIC code. 



100 FOR 1 = 1 TO 1024 STEP 1 p'loop 1024 times 
200 PRINT "*"; 'each time print ' 

300 NEXT I L'continue loop 



The loop is initialized by the FOR . . . TO . . . STEP . . . state- 
ment which tells the BASIC interpreter to repeat the action from 1 
to 1024 times using variable "I" to count the number of times 
through the loop. The NEXT statement marks the end of the loop 
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and causes control to return to the FOR . . . TO . . . STEP statement 
for the next repetition of the loop. Within the loop between the 
FOR . . . TO . . . STEP and NEXT statements, loop action of vir- 
tually any type or range may occur. ( If "STEP" is not used, an in- 
crement of 1 is assumed; we've included STEP in this example for 
clarity. ) 

BASIC programs use two types of operands-constants and vari- 
ables. Constants are exactly that-set values that never change, for 
example, 3.14159 for pi and 999-99-9999 for a Social Security num- 
ber. Variables can change and are simply names that the program 
sets aside for holding such things as index counts, subtotals, and 
character stiings. Variable names are defined by one or two (or 
more) alphanumeric characters, the first of which must be alpha- 
betic (AA, Al, Z2 are vahd variable names). Variable types are 
related to the size and accuracy of the data that will be held in the 
variable. 

Integer variables hold the number range -32768 to -f 32767 and 
are denoted by variables with a "%" suffix, as in A2% or A9%. 
Single-precision variables allow mixed numbers with seven decimal 
digits (1.234343 X 10-«) and a range of lO-s^to lO+^s (wide enough 
to accommodate subatomic to stellar measurements). Single-preci- 
sion variables are denoted by a "!" suffix as in A2! or Z2!, or simply 
the variable name without any suffix. Double-precision variables 
extend the number of significant digits ( all of the "accurate" digits ) 
that may be held to 14 (1.2343434343434 X 10") and are denoted 
by a "#" suffix as in A2# or Al#. 

Variable types may also be defined by a set of DEFINE VARI- 
ABLE TYPE commands that define a range of alphabetic names 
that specify an appropriate variable type. 

There are certain rules for the use of the proper variable types 
in BASIC programming. These are discussed in Chapter 2 along 
with the storage requirements for variable types and information 
relating to precision. Chapter 2 also discusses the binary number- 
ing system and the logical operators AND, OR, and NOT. 

STRING statements allow a program to handle strings of charac- 
ters such as "TRS-80" or "1234 BASIC STREET, LEVEL II." You 
can manipulate portions of strings with the LEFT$, MID$, or 
RIGHT$ statements. With other statements, you can convert be- 
tween strings and numeric data (ASC, CHR$, STR$, VAL). 
STRING$ generates a string composed of the same character re- 
peated a specified number of times. LEN computes the length of 
a given string, while FRE$ finds the remaining space available in 
RAM for strings of all types. Strings are one of the most powerful 
features of Level 11 BASIC, and we'll cover them in Chapter 3. 

PRINT statements cause an output of data to the video display. 
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PRINT LIST prints one or more items including variables or char- 
acter strings. 

100 PRINT "A EQUALS ";A 'print value of A 

for example, prints "A EQUALSb" followed by the value of variable 
A. The PRINT TAB function allows a program to "tab over" to a 
specified column before printing another item. 

100 PRINT TAB(50);A 'tab and print A 

for example, moves the display cursor to tab position 50 and then 
prints the value of variable A. 

PRINT @ prints at any given character position (out of 1024) on 
the video display. 

100 PRINT @512, "THIS IS LINE 8" 'print at line 8 

prints the message at line 8 of the 16 lines of the screen, starting 
at the extreme left. 

PRINT USING $ is a somewhat complicated and powerful state- 
ment that allows you to format printing in regard to leading zeroes, 
decimal points, and a bunch of other goodies. We'll talk about it 
in detail along with the other PRINT statements in Chapter 4. 

GRAPHICS statements are for those of you who want to display 
graphics data on the video display. Graphics means "non-character" 
data. The Display is divided up into a matrix of 128 by 48 elements, 
each one of which can be turned on (SET), off (RESET), or tested 
(POINT). Other graphics statements clear the entire screen (CLS) 
or find the current cursor position (POS). There are many tech- 
niques for displaying both character and graphics data on the video 
display, and we'll get to those in Chapter 5. 

DATA TABLES and ARRAY-type statements define data lists 
(DATA) or arrays of data (DIM). Data Hsts are lists of constants 
that may be read sequentially using READ and RESTORE state- 
ments. Arrays are ordered lists of data in one or more dimensions 
that can be accessed in random fashion. Data lists and arrays are 
covered in Chapter 6. Searching and sorting data in lists and arrays, 
a very important topic, is covered in Chapter 7. 

TRS-80 Level II BASIC includes a set of built-in FUNCTIONS. 
These functions are statements that perform specialized functions 
rather than general-purpose actions. Trigonometric functions in 
Level II BASIC include SIN (sine of an angle), COS (cosine of an 
angle), TAN (tangent of an angle), and ATN (arc tangent). Num- 
erical and mathematical functions include ABS (absolute value), 
CDBL (double-precision), CINT (integer), CSNG (single-preci- 
sion), EXP (natural exponential, or antilog), FIX (truncation), 
INT (whole number), LOG (natural log), SGN (sign of a num- 
ber), and SQR (square root). RANDOM and RND allow genera- 
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Hon of random numbers for simulation, games, and other applica- 
tions. Functions and their use in various applications are described 
in Chapter 8. 

BASIC allows cassette tape operations using two statement 
types, INPUT #-1 and PRINT #-1. INPUT #-1 inputs a single 
record of data for use in a program, while PRINT #-1 outputs a 
single record to cassette tape. Each record may contain a number 
of variables or constant data. Chapter 9 describes practical appli- 
cations of cassette tape. 

A number of statements and functions in BASIC allow for error 
checking in programs. Errors occur as a result of operator error, 
illegal operations (such as division by zero), or hardware faults. 
When errors do occur. Level II BASIC provides the mechanism 
to unravel the error and take corrective action. 

ERROR lets you simulate an error condition to check out the 
error-handling portion of your BASIC code. ERL and ERR/2-H 
return the line number at which the error occurred and the error 
code number, respectively. ON ERROR GOTO . . . sets up the line 
number of the error-processing routine, while RESUME ... re- 
sumes program execution after an error occurs. Errors are ti-eated 
in Chapter 10 (if you start making too many of them, maybe you 
should skip right to that chapter). 

While most programmers want to program exclusively in the 
high-level BASIC language, there are provisions in the interpreter 
to interface BASIC programs with machine code. The advantages 
are execution speeds of up to several hundred times the BASIC 
interpi-etation speed and added versatility. 

PEEK and POKE allow you to look at or change memory loca- 
tions in ROM or RAM to change the action of the BASIC inter- 
preter or just for your own enlightenment. A special USR call 
allows BASIC to pass control to an assembly-language routine. 
VARPTR finds the address of a BASIC variable for the purpose 
of passing parameters or for direct examination or modification. 

Chapter 11 discusses how assembly language routines can be 
used in BASIC. Chapter 12 uses PEEKs, POKEs, and other state- 
ments to reveal some of the deep, dark secrets of the "internals" 
of the BASIC interpreter and the organization of memory. 

Number Crunchies, the New Computer Energy Food 

We've described most of the BASIC statements available in 
TRS-80 Level II BASIC, but we haven't really talked a great deal 
about "number-crunching" operators, the processing that BASIC 
can perform. Of course, BASIC can add { + ), subtract (-), multi- 
ply {"), and divide (/) variables and constants, but the impres- 
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sive thing is that BASIC does it while automatically adjusting the 
number of digits and range of the number. You (the programmer) 
are relieved of the responsibility of remembering number ranges 
and decimal-point position (unlike early computers . . . may not 
sound like a big deal, but believe me, it is . . .). Exponentiation 
(t) is also easily accomplished. Typical examples of sequences of 
processing operations are shown below 



100 4/3*PI*Rt3 



'find volume of sphere 



200 ST=GR*(100-DS) 'gross times discounted price 
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We've glossed over another operator, the "=" or equivalence 
operator. An equals sign, of course, sets a variable on the left of 
the equation equal to an expression, constant, or variable on the 
right of the equation. The forgotten statement type "LET" may be 
used in conjunction with an equals sign as in 

100 LET A= 1.235 

but the LET really only remains as an anachronism for compati- 
bility with previous BASICs. There is really no reason to use it, and 
we will not in this book. 

Not only can BASIC perform arithmetic and exponentiation 
functions, but it can also perform comparisons. Comparisons of 
less than (<), greater than (>), less than or equal (<=), greater 
than or equal (>=), equal ( = ), and not equal (<>) are easily 
performed on all types of variables including string variables. A 
unique string concatenation operator ( + ) allows two or more 
strings to be joined together. 

100 A$ = "NOW IS"+" THE TIME" +" FOR . . ." 



Command Performance 

Up to this point in our monograph on Level II BASIC, we've 
been talking about BASIC program operation. As you know from 
the Level II BASIC Reference Manual, however, there are really 
four modes of operation— Command, Execution, Edit, and Monitor. 

The Command mode is essentially a supervising mode that con- 
trols the loading of a BASIC program, some cursory editing, de- 
bugging, and listing. 

A BASIC program on cassette tape is loaded by the command 
CLOAD and can be checked for accuracy with a program in RAM 
by the CLOAD? command. Another cassette-related command, 
CSAVE, saves the BASIC program in RAM memory on cassette 
tape. 

The three other modes of operation are invoked by the three 
commands RUN (execute), EDIT (edit mode), and SYSTEM 
(monitor). RUN causes the current BASIC program in RAM to, 
well . . . , run, starting at the first line number, if none is specified, 
or at a specified line number. ( RUN 10000 starts execution at line 
10000.) Of course, you can stop any program that is running by 
pressing the BREAK key. 

EDIT invokes the edit mode, which we'll discuss in a moment. 
(However, the Command mode allows some limited editing.) 
Lines can be deleted by typing the line number followed by 
ENTER. Lines can be modified simply by retyping the line num- 
ber with the new contents. Lines can be inserted using the tech- 
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nique we spoke of in an earlier example— using a line number in 
the interval between two existing line numbers. Another delete 
command (strangely enough designated DELETE) deletes a range 
of lines (DELETE 10000-10999 deletes all program lines from 
10000 to 10999). The last editing-type command is AUTO, which 
provides automatic line numbering, starting at a given line num- 
ber and incrementing by a given value. (AUTO 100,20, for ex- 
ample, starts at line 100 and increments by 20 for each new line. ) 

The command CLEAR clears a given area for strings. Since the 
string area is at the top of RAM memory, the BASIC interpreter 
must know where the string area ends and everything else begins. 
(We'll discuss this topic in Chapter 3.) 

The CONT command continues after a STOP statement. The 
STOP statement can be used to stop execution at any point, after 
which you can examine variables and other data to your heart's 
content (and then CONTinue on). 

Two other commands related to debugging, TRON and TROFF 
(trace on and trace off), turn the trace capability on or off. The 
trace function displays each line number on the screen as it is exe- 
cuted, so you can see the program flow. The STOP statement and 
CONT, TRON, and TROFF commands are discussed in Chapter 
10 in a general discussion of debugging, a nasty job of getting rid 
of 8-bit and other species of program bugs. 

NEW is a doomsday command that wipes out the current BASIC 
program in RAM memory and initiahzes all BASIC interpreter pa- 
rameters. ( Use it carefully! ) 

The LIST command Hsts the current BASIC program on the 
screen; LLIST performs the same function on a system line printer. 

The SYSTEM command invokes the monitor mode, used to load 
machine-language tapes into the system and to transfer control to 
machine-language routines that have been loaded. These topics are 
covered in Chapter 11. 

Editors Are Not So Hard Bitten After All 

The Edit Mode in Level II BASIC is invoked by the EDIT com- 
mand. The Edit actions are well documented in the Level II BASIC 
Reference Manual, but we'll provide a recap here. Basically, the 
Edit Mode allows an edit of an individual hne. The cursor may be 
positioned one position to the right on the line by typing "space" 
or n positions to the right by typing n space (20 "space" moves 
the cursor 20 positions to the right). The cursor may be moved to 
the left one position by typing "<-" or n spaces by typing "n-^." 

Once the cursor is positioned to the proper point on the line, you 
can delete characters by typing "D" (or several characters can be 
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deleted by typing "nD"). You can change characters by typing "C" 
followed by the character to be used in place of the changed char- 
acter (or by "nC," followed by the string of characters to be used 
for the change). Characters can be inserted by typing "I" followed 
by the characters to be inserted. 

The "E" character Ends the Edit and saves the changes made, 
while the Q command Quits the Edit and cancels all changes, 
leaving the line as it was before the Edit. The A command is simi- 
lar to the Q except that it cancels All changes already made, but 
the system remains in the Edit mode. The L command Lists the 
entire line. 

The H command Hacks off the line from the current cursor po- 
sition and sets the insert mode; now you can insert additional char- 
acters. The X command is similar, but positions the cursor to the 
end of the line for the insert. 

The K command Kills all characters up to a specified character 
(Kc) or kills all characters up to the nth occurrence of a specified 
character nKc. This last command would kill the "NOWISTHE" 
portion of "NOWISTHETIMEFORALLGOODPROGRAMMERS" 
with a command of "2KT." 

The S command enables you to Search for a given character (Sc) 
or the nth occurrence of the character. A command of "2ST," for 
example, would position the cursor as follows: 

NOW IS THE IIME FOR ALL GOOD PROGRAMMERS 

Have you memorized the list? ( Guard . . . find out the address of 
that reader in Des Moines . . .) All of this information can be 
gleaned from the Level II BASIC Reference Manual, but we've 
presented it here as a review. We'll be using a lot of examples in 
the chapters to follow. You'll be able to learn the use of some of 
the more exotic statements by practical example, so don't be too 
dismayed if you don't understand all of the commands or their 
applications. That's what we're here for. 
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CHAPTER 2 



To Be Precise . » « 



We'll be considering the subjects of binary numbers, BASIC va- 
riables, number ranges, and precision in this chapter. These are not 
as stuffy as they sound and are easier to understand than you might 
think. Don't let the subjects scare you off . . . {Guard! Stop that 
reader from turning the page . . . ) You will be amply rewarded with 
BASIC programs that are faster and use up less memory, and in the 
bargain you may get to see some of the internal workings of BASIC. 

A Long Time Ago in a Computer System Far, Far Away 

Let's digress for a moment and talk about the Zzarth race of the 
Siiius star system. As we all know, Zzarthians have 8 hands with 
one finger on each hand. (Baseball umpires there have a heck of a 
time with signals. . . .) Back in Zzarthian antiquity when the frog- 
like Zzarthian speech was first developing, some of the more astute 
members of the tribe used fingers to denote the number of znab- 
beasts that were seen in the hunt. One finger meant one znabbeast, 
two meant two, and so forth. The limit of this was, of course, 8 
znabbeasts, represented by eight arms with 8 fingers held high as 
shown in Figure 2-1. 

Since the number of znabbeasts in a qwany varied from several 
to well over a hundred, this description left something to be desired. 
One day, however, a strange monolith appeared with the markings 
"A registered trademark of TANDY Corporation" in the lower-right 
hand corner. . . . The following day, one of the younger Zzarthians 
(by the name of Ed, if you must know) approached the elders' 
council and declared, "I've just invented a new system to report on 
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znabbeasts." Naturally reluctant, as are all elders when approached 
by radicals, the elders soon became excited as the advantages of 
this system became apparent. 

"Watch" said Ed. "One znabbeast is represented by arm with 
one finger held out. Two znabbeasts by arm 1 with its finger. Three 
by arm 1 and arm 0. Four by arm 2 only. Five by arm 2 and arm 0." 

"Wait!" cried the elders in dismay. "Write it up and make some 
photocopies for us so we'll be able to understand it a little better." 

Table 2-1 is what Ed created. 

The Zzarthian system became known as the binary system after 
the chief. Bin Ary, claimed credit for it, as elders are wont to do. 
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Table 2-1. Binary Representation 
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Figure 2-1. Zzarthian binary representation. 
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It is exactly equivalent to the system used in digital computers to- 
day. Each collection of 8 arms is called a byte. Each arm has one 
finger, which is either a 1 (up) or (down). Each arm in efl^ect 
represents a power of two just as our decimal system represents a 
power of ten. 

The largest number that can be held in a byte is 11111111, or 
128 + 64 + 32 + 16 + 8 + 4 + 2 + 1 = 255. The smallest number is 
00000000, or 0. Any number from through 255 can be repre- 
sented by zeros and ones in the appropriate positions. 

This scheme of positional notation can be extended to two or 
more bytes. When this is done for two bytes, much larger numbers 
can be represented, as shown in Table 2-2. Note that the 15th bit, 
or binary digit, is a 0, so that in two bytes we have only 15 bits 
(15-0) instead of 16. Well see why later. 



Table 2-2. Two-Byte Binary Representation 



Binary 



Decimal 



15 14 13 12 11 10 9 a 7 6 5 4 3 2 1 



1 



00000000000 
00000000001 



00100000000 
00100000001 



000000000 



00000000000 
00000000001 



1 1 1 1 01010111011 



1 1 1 1 11111111111 



256 
257 



8192 



24576 
24577 



31419 



32767 



Integer Variables 

This scheme of two-byte storage should enable us to store num- 
bers from (00000000/00000000) through 16,384 + 8192 -I- 4096 + 
2048 -f 1024 + 512 4- 256 -f- 128 + 64 -I- 32 -r 16 -f 8 -t- 4 -t- 2 4-1 = 
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32,767 (01111111/ 11111111). Let's look at the two-byte storage for- 
mat in BASIC. It's called integer format and is defined by a variable 
with a % sign after it, such as A%, AA%, or Zl%. 

First of all, let's verify that we can indeed store through 32,767. 
The program below stores the input value but gives an OV (over- 
flow) error for values greater than 32,767. 



100 INPUT A% 
200 GOTO 100 



'input an integer value 
'loop on input 



By adding a VARPTR statement and some PEEK statements, we 
can see where in RAM memory the A% variable is stored and what 
it looks like. The VARPTR returns the RAM address where A% is 
stored. RAM, as you know, occupies from 16,384 to 32,767 (16K 
System), 49,150 (32K System), or 65,535 (48K System), each lo- 
cation containing one byte (8-arms worth) of data. Each RAM 
location is "addressed" by reference to an address value of 16,384 
through 32,767 (16K), 49,150 (32K), or 65,535 (48K). PEEK re- 
trieves the value of each byte, which is 0-255. 



100 INPUT AX 

200 B=VARPTR(A'/.) 

30B PRINT B 

400 PRINT PEEK(B) 

50B PRINT PEEK(B+1) 

600 SOTO 100 



~ '9et integer variable 

'find address 

'print it 

'print Is bYte 

'print fTis bYte 
' — 'loop for next 



The first number printed in this program is the address of A%. 
The next two numbers printed are the contents of the two bytes 
that make up the variable. Try inputs from 0-32767 (or above) 
and see what happens. 

If you tried values for A% between and 255, you saw that the 
first byte (Is, or least significant byte) was used to store the value, 
and the second was zero. For example, a value of 10 results in 

10 (first byte) 
(second byte) 

and a value of 255 results in 

255 (first byte) 

(second byte) 

If you tried values larger than 255, you saw that both the second 
and first bytes were used. For example, a value of 257 results in 

1 (first byte) 

1 (second byte) 

and a value of 1000 results in 

232 (first byte) 
3 (second byte) 
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8 "BITS" PER BYTE 
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Figure 2-2. Two-byte storage. 

The first byte is the low-order byte, while the second byte is the 
high-order byte. This arrangement is true for all byte storage in the 
TRS-80 and is shown in Figure 2-2 for various values. We can see 
this better if we use some additional code to recompute the input 
value from the two bytes at which we've PEEKed. 



1000 INPUT A7. 

1100 B=VARPTR(Ay.) 

1200 PRINT B 

1300 PRINT PEEK<B) 

1400 PRINT PEEK(B+1 ) 

15B0 C=PEEK(B+1 )*256+PEEK<B) 

1600 PRINT C 

1700 GOTO 1000 



'9et inte9er- variable 
'find address 
'print It 
'print Is brte 
'print tips byte 
'recompute input value 
'and print it 
' 1 OOP tor next 



The 1500 statement verifies that the two bytes do make up the 
input value by multiplying the high-order byte by 256 and adding 
the low-order byte, essentially converting from two 8-bit bytes into 
a 16-bit binary value. 

As an example, suppose that we entered A% = 1000. The low- 
order byte (PEEK (B)) is 232, and the high-order byte (PEEK 
(B-fl)) is 3. Multiplying 3 by 256 is 768, plus 232 equals 1000. 



A% = 1000 -^ 



PEEK(B) =232 



PEEK(B-M) =3 
3 ' 256 -t- 232 = 1000 
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What about that 15th bit? The 15th bit is used for a sign bit. 
Not only can we store to +32767 in two bytes, but we can store 
—1 to —32768. Run the program above with negative input values 
and let's see what we get. 

This time we displayed mysterious data. Inputting —111, for ex- 
ample, displays 

?-iii 

145 
255 
65425 

The first two values are the contents of the two bytes for variable 
A%, but the next value is certainly not —111. The answer here is 
that negative numbers are stored in a form called two's comple- 
ment in binary. In this form, negative numbers are stored by find- 
ing the positive equivalent in binary and then changing all zero 
bits to one, all one bits to zero, and adding one. This simplifies 
hardware design and is used in almost all digital computers. To 
find the equivalent negative number for A%, check the value C = 
PEEK(B+1) »256 + PEEK(B). If it is over 32767, perform the 
computation 65536 — C, and you will have the equivalent negative 
number stored. 

1600 IF C>32767 THEN PRINT "-";65536-C ELSE PRINT C 

The integer format is good for expressing the range of numbers 
from -32768 through to -1-32767. It always requires two bytes 
and will never approximate the number, but will hold the precise 
number. If you attempt to use an integer format with a result 
greater than -f-32767 or less than -32768, an OV (overflow) error 
will result, since the BASIC interpreter does not know how to 
handle an integer number that requires more than two bytes. 



Murphy's Rule Number 32K 

At this point, we had better mention another rule which is re- 
lated to the computation of negative numbers. When PEEKs and 
POKES are used in this book, they will work fine if the address 
argument is 32767 or less. For example, 

100 FOR 1 = to 32767 'peek at memory loop 

200 PRINT PEEK (I) 'i see you 

300 NEXT I 'loop here 

will print out all address locations from through 32767. However, 
if the address is 32768 or more, the value used in the PEEK or 
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POKE must be (ADDRESS-65536). The reason for this is that 
PEEK and POKE look for an integer limit of +32767. Numbers 
over that limit are treated as invalid numbers. PEEK and POKE 
must therefore be fooled into accepting addresses in the range of 
32768-65535. An example of this is 

100 FOR 1=0 TO 65535 'peek at memory loop 

200 IF l< 32768 PRINT PEEK(I) ELSE PRINT PEEK (1-65536) 

300 NEXT I 'loop here 

Most of the examples in this book use the low^er 32K for POKE- 
ing values or in PEEKing at data. However, if an address in the 
upper 32K is involved, an OV error will result unless the computa- 
tion above is performed. 

The % suffix specifies integer format, but this format may also 
be specified by a define variable type statement such as 

100 DEFINT A-B 'all variables A-B will be integer 

The above example makes all variables in the range A through B 
automatic integer variables. 

Single-Precision Variables 

Obviously, we would have some difficulty in dealing only with 
integer variables. It would not even allow reasonable calculations 
on checking accounts (although the ability to express negative 
numbers might conceivably help in dealing with my checking ac- 
count). One of the most valuable features of BASIC is that it al- 
lows us to operate with very large and very small numbers auto- 
matically, unlike machine language, the "Tiny" languages, or other 
less powerful languages. We are able to do this with single-preci- 
sion and double-precision numbers. 

Let's use the following code to define the number ranges and 
precision for this type of number. By the way, this format is the 
"default" format for variables in the system, although a suffix of 
"1" may also be used. 

2000 INPUT A 'input single-precision 

2100 A~A/2 n'find smaller values 

2200 PRINT A 'print 

2300 GOTO 2100 '-'ioop for next 

In inputting various values of A, we can see that the smallest 
number that can be held in this format is l.XXXE-38 (use 
"SHIFT®" to stop the display at any time). By changing state- 
ment 2100 to A = A'2, we see also that the largest number is about 
5.XXXE-)-38. (The E format simply means that the foUovdng num- 
ber is a power of 10. E-38 means 10-38, and E-l-38 means W^) 

34 



The complete range of single-precision variables, then, is about 76 
powers of 10, providing the capabiHty to express subatomic dis- 
tances to the number of atoms in the universe! 

The precision, however, is a different story. This format allows 
only seven decimal digits of precision. (BASIC will print only six 
of these. ) Digits beyond that range are rounded off. When we mul- 
tiply 123456 by 33 we should get 4,074,048, but actually get 
4,074,050. Once again, the reason for this is limitations on variable 
storage. Single-precision variables take up four bytes of storage in 
RAM. About 3 bytes of that is devoted to the significant-digit part, 
or mantissa, of the number representation, while one byte is'^ de- 
voted to the exponent, as shown in Figure 2-3. The 3-byte integer 
provides 24 bits ( one bit is always 1 ) to allow a range of numbers 



BYTEO 


BYTEl 


BYTE 2 


BYTE 3 


LEAST SIG BYTE 


NEXT SIG BYTE 


MOST SIG BYTE 


EXPONENT 



I SIGN EXPONENT 

1 = NEGATIVE IS POWER 

= POSITIVE OF TWO 

Figure 2-3. Single-precision storage. 

from about -16,777,216 to -H6,777,215 to be expressed without 
loss of digits. (The exponent is a power of two allowing about 
2-128 to 2+12' to be handled, or roughly 10-" to 10+".) Up to a 
certain point, a number is held as straight binary in the 24 bits, 
while beyond this point the integer holds only the most significant 
portion of the number. 

You may (if you have masochistic tendencies) care to further 
explore the wonderful world of floating-point formats by using 
the VARPTR command to retrieve and display the storage of data 
in a single-precision variable, as shown below (see Figure 2-4). 



3000 INPUT A 

3100 B=VARPTR<A) 

3200 PRINT PEEK(B),PEEK<B+1). 

3300 PRINT PEEK (B+2)i PEEK (B+3) 

3400 GOTO 3000 



■'input siri91 e-precisi 
'find location 
'print first 2 brtes 
' print next 2 bvtes 

■ ' 1 OOP for- next 



Double or Nothing 

Because seven decimal digits are not quite precision enough for 
some calculations (imagine trying to compute federal budgets in 
six figures), Level II BASIC provides for a double-precision for- 
mat. As the astute reader .may have surmised, double-precision 
doubles (or more than doubles) the amount of precision available 
in BASIC. As a matter of fact, it allows for 17 significant deci- 
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VARIABLE IN MEMORY 









221 













129 













130 










64 


130 







80 


80 


140 







53 


2 


144 




160 


194 


34 


147 



DECIMAL 
NUMBER 
ENTERED 





3333 



33333 



333333 



ALWAYS A 
ONE BIT 



80 



\ 



140: 

140 - 128 = 12 BITS IN INTEGER 



(1)101 0000 0101 0000 



+ 3333 

NUMBER IN 12 BITS 

Figure 2-4. Single-precision storage examples. 

mal digits (now we're finally approaching the realm of some of 
the smaller government agencies). Only 16 digits will ever be 
PRINTed. 

To obtain this precision, the integer portion of the floating point 
variable is increased in size from 3 bytes (24 bits) to 7 bytes, as 
shown in Figure 2-5. Seven bytes allow 56 bits of precision, or 
approximately to 36,000,000,000,000,000. Note that the range of 
the number expressed is still limited by the exponent portion of 
the variable. 

Double-precision variables are represented by a # suffix, as in 
"A#" or "Z2#". When the double precision is used in scientific 
notation, a "D" replaces the "E" for the exponent, as, for example, 
in "1.23456789D+1S". 
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BYTEO 



BYTEl 



BYTE 2 



BYTE 3 



LEAST SIG BYTE 


NEXT LST SIG BYTE 


^ 




BYTE 4 


BYTES 


BYTE 6 


BYTE? 





NEXT MOST SIG BYTE 


MOST SIG BYTE 




EXPONENT 






1 SIGN 
1 = NEGATIVE 
= POSITIVE 





Figure 2-5. Double-precision storage. 

As in the case of integers and single-precision variables, double- 
precision variables may be defined by a DEFDBL statement that 
specifies a variable range. 

100 DEFDBL A-B 'all variables A-B will be double precision 

specifies that all variables starting with A or B will be double- 
precision variables. 

If you're still harboring latent masochistic tendencies (evidenced 
by listening to CSAVE tapes on your 150-watt stereo), you can in- 
vestigate double-precision formats and storage by 



100 INPUT A« 
200 B=VARPTR<Att) 
300 FOR 1=0 TO 7 
400 PRINT PEEK<B+I). 
500 NEXT 
600 (50T0 100 



r; 



input double-precision 
find 1 ocat ion 

L'set 8 time loop 
'print brte 
'loop to next print 
loop ba.:!-; to n:.::t input 



When should integers be used? When should single-precision 
variables be used? And when should double-precision variables be 
used? Fortunately, the great French mathematician Blaise Pascal 
gave us the answer in 

A Treatise on the Use of Numbers Great and Small 
With Special Reference to the TRS-80 

In the old days of computers, three years ago, memory was very 
dear. Today, one can buy a bit of memory (pun intended) for a 
penny or so a bit. The point is that even a parsimonious (Editor's 
note: Stay away from polysyllabic words!) programmer can afford 
to use single-precision (default) variables and not be very con- 
cerned about memory requirements. Double-precision can be used 
when required, but shouldn't be used for all variables, because, in 
addition to memory storage requirements, the computation speed 
is less efficient. The exception to the use of single-precision over 
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integer variables is when an array of variables is used. Arrays, by 
their very nature (see Chapter 6) take up a great deal of memory 
space, and it is prudent to use integer variables if possible. Other- 
wise, don't be too concerned about widespread use of single-pre- 
cision, rather than integer variables. 

As a recap, Table 2-3 shows the ranges, precision, and storage 
requirements of integer, single-precision, and double-precision vari- 
ables. Memorize this table and then eat it to avoid revealing inter- 
nal secrets to other personal-computer users. 

Table 2-3. Variable Ranges, Precision, and Storage 



Varioble 
Type 


Range 


Proclsion 


Storage 


Integer 


-32768 to 
4-32767 


5 integer 
decimal digits 


2 bytes 


Single- 
precision 


About 1 X 10^^ 
to 1 X 10-38 


7 decimal 
digits 


4 bytes 


Double- 
precision 


About 1 X 10^8 
to 1 X 10-38 


17 
decimal digits 


8 bytes 



Once More Unto the Breach 

I'll bet you thought we were done with discussions of binary 
number systems. It's our unpleasant duty to inform you that we'll 
have to continue the discussion {Guard! Watch that BASIC pro- 
grammer . . .). Actually, the commands we're going to discuss here 
are very simple and should pose no problem in understanding. 
What's more, they'll enable you to manipulate data down to the bit 
level, which can be a very powerful capability and one that many 
BASIC interpreters do not provide. The three commands we'll be 
discussing in this section are AND, OR, and NOT. 

These commands are called logical operators. They are used to 
handle logical expressions. What are logical expressions? Generally, 
logical expressions can be equated to true and false. True and false, 
of course, can be translated into a binary 1 and 0, respectively. Sup- 
pose we write a logical expression for a visit to your mother-in-law's 
house. We will call the end result of the expression "VISIT". If 
VISIT = 1, we will go on the journey; if VISIT = 0, we will not. 
The expression I usually work with is: 

VISIT = (GAS IN CAR) AND (NOT WEEKDAY) AND (NOT BEHIND 

IN WRITING BOOKS) AND (NOT TOO HOT) AND (FEELING 
OK) AND (HAVE ENOUGH MONEY) 
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This expression says that if we have gas and if it is not a weekday 
AND so forth . . . then we can perform the visit. By equating each 
of these expressions to a 1 (true) or (false), then we see that 

1 = T AND 1 AND 1 AND 1 AND 1 AND 1 

VISIT will equal 1 (true) if and only if all of the conditions are 
true. 

Another logical expression might be one relating to one called 
OVERDRAWN. OVERDRAWN is true (1) or false (0) as fol- 
lows: 

OVERDRAWN = (WIFE MAKES CHECKING ACCT ERROR) OR (HUSBAND MAKES 

CHECKING ACCT ERROR) OR (UNEXPECTED BILL) OR (EXPECTED BILL) 

As we can see, OVERDRAWN is almost always true (1) because 
one OR the other condition is probably true. 

A third type of logical expression that will illustrate logical oper- 
ators is 

SOLVENT = NOT (OVERDRAWN) 

This is easy to understand. 

There is nothing magical, therefore, about logical operators or 
expressions. They were developed by Plato, George Boole ( a 19th 
century mathematician), Claude Shannon (a 20th century research 
engineer), and others. They are really an attempt to define real- 
world conditions in convenient symbolic form. 

The AND function, as we have seen, states that a result condition 
is true if one condition and another (and others) are true. If either 
of the conditions is false, the result condition is false. If we are 
working with two conditions, we can diagram this as: 

tST CONDITION 11 
2ND CONDITION 10 1 

RESULT 1 

The OR function states that a result condition is true if either one 
OR another (or others) is true. We can state this as: 

1ST CONDITION 11 
2ND CONDITION I I 

RESULT 111 

The NOT function states that the result condition is true if the 
input condition is false and false if the input condition is true 

INPUT CONDITION 1 
RESULT 1 

For the most part, we spend a great deal of time in BASIC pro- 
grams writing down logical conditions, most of which are em- 
bedded in IF statements 
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convert to binary 

find bit 
'next =iuotient 



110 CLE -clear screen 

120 INPUT "VALUE 1=" ;A 'input value 1 

130 IF A:-=0 and A<256 GOTO 140 ELSE 60T0 1^0 

140 INPUT "VALUE 2=";B J "Tf" "" ^ 

t50 IF B>=0 AND A<256 SOTO 160 ELSE SOTO 140 

'l60 INPUT "AND, OR, OR NOT=- JAt ','!;:"* *r!.„, 

170 IF A*<-:>"AND" AND A«<>"OR" AND ASO'NOT" SOTO 160 

180 PRINT "VALUE 1 IN DECIMAL IS ";A;"IN BINARY IS : 

7mm C=A '^'"■' subroutine 

210 GOSUB 10000 „ „ ',=2?',!Cj ^S.'""^"' 

2-;'0 PRINT "VALUE 2 IN DECIMAL IB "SB: "IN BINARY IB . 
''30 C=B '^'"^ subroutine 

240 GOSUB 10000 -convert to binary 

"60 IF AS="AND" THEN C=A AND B 'find and result 

263 IF A$="OR" THEN C=A OR B 'find or result 

265 IF AS="NOT" THEN C=NOT B 'find not result 

270 PRINT "RESULT IN DECIMAL IS "!C;"IN BINARY IS ; 
280 SOSUB 10000 
290 IF INKEYS="" GOTO 290 ELSE GOTO 110 

10B00 B0=C-INT(C/2>»2 'rind bit 

10010 C=INT(C/2) 'rie?:* luotie 

10020 Bl=C-INT<C/2)*2 

10030 C=INT(C/2) 

10040 B2=C-INT(C/2)»2 

10050 C=INT(C/2) 

1006B B3=C-INT(C/2)*2 

10070 C=INT(C/2) 

10080 B4=C-INT(C/2)»2 

10090 C=INT{C/2) 

10100 B5=C-INT(C/2)»2 

10110 C=INT<C/2) 

10120 B6=C-INT<C/2)»2 

10130 C=INT(C/2) 

10140 B7=C-INT(C/2>*2 

10150 PRINT B7;B6;B5;B4;B3!B2;B1;B0 'print binar-y 

10160 RETURN '^<^t""' *° ""'"^ "'■'"' 

Figure 2-6. Binary exerciser program. 
100 IF (A=0 AND B=0) GOTO 1000 



200 IF {A<5 AND A>0) GOTO 1115 



1000 IF (A=l OR A=2) A=A + 17 



2000 IF {A$ = "ED" OR A$ ="JIM") THEN B$="ANIMAL" ELSE B$="MINERAl" 

Ho-wever, logical operators can also be used with binary values. 
Let's see ho-w this works by constructing a binary exercise program. 
This program will illustrate binary operations by allowing you to 
input two 8-bit values. The values will be displayed in decimal and 
binary, and then you can specify an and, or, or not function to 
observe how the binary functions work. See Figure 2-6. 

The key to this program is the decimal-to-binary conversion sub- 
routine at 10000. It implements a conversion from decimal to binary 
called "divide and save remainders." To see how this works, let's 
convert a decimal number to binary on paper, as shown in Figure 
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2-7. We divide the decimal number by 2 and save remainders. The 
remainders in reverse order are the binary number. This method 
always works for any size of decimal number, although it does get 
tedious for numbers over 3 trillion. In the program, BO is the first 
remainder, Bl the next, up to B7 for the last. The "INT" function 
finds the integer (quotient without remainder) of the divide. Mul- 
tiplying the quotient by two and subtracting it from the current 
number gives the remainder. At the end of the subroutine, the re- 
mainders are printed in reverse order. 

This program could have been made much shorter by using ar- 
rays and other clever coding, but the important thing here is to see 
how the binary operators work. Entering VALUE 1 = 255 and 
VALUE 2 = 15, and specifying an "and", for example, results in 
an AND of 255 and 15. The value of 255 in binary is 



1111 



1111 



— 1 

— 2 

— 4 

— 8 

— 16 

— 32 

— 64 
-128 

255 



while the value of 15 is 







1111 



15 

When these two values are ANDed, each bit position of the eight 
is ANDed separately and does not affect any other bit position. 

11111111 

AND AND AND AND AND 1 AND 1 AND 1 AND 1 



We know from the rules of logical operators that and is 0, 
1 AND is 0, AND 1 is 0, and 1 and 1 is 1, and the result reflects 
this. 

As another example, let's or 170 and 112. Expressed in binary, 
these values are 
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Rl- 


21 1 


Rl 


2[T' 


RO 


irr 


RO 


21 12 


RO 


21 24 


RO 


2! 48 


RO 


21 96 


Rl 


2i 193 


RO 


21 386 


RO 


21 772 


RO 


21 1544 


Rl 


21 3089 


RO 


21 6178 


Rl 


21 12357 





11000001000101 = 12357 



Figure 2-7. Pencil-and-paper decimal-to-binary conversion. 



10 10 



10 10 

1 



111 







— 2 
— 8 
-32 
-128 

170 



-16 
-32 

-64 



112 



As in the case of ANDing, each bit is considered separately 

10 10 10 10 
ORO ORl ORl ORl ORO ORO ORO ORO 



We know from the rules of ORing that or is 0, 1 or is 1, or 
1 is 1, and 1 or 1 is 1, and this is shown in the result. 

The third example is the not. The not in this program takes the 
NOT function of VALUE B as the result. If the input value is 170, 
then the not looks at each bit and takes the complement. This is 
just a two-dollar word for the opposite state. If a bit is a 0, then 
the result bit is a 1. If a bit is a 1, then the result bit is a 0. 

10 10 10 10 

N OT NOT NOT NOT NOT NOT NOT NOT 

10 10 10 1 

At this point, you're probably saying, "Fine, we and 255 and 15 
and get 15, we or 170 and 112 and get 250, and we not 170 and 
get 85— what's the practical application?" (Aha . . . you were say- 
ing that! ) The and, or, and not are not used as frequently as com- 
mon BASIC operators, but they can be very valuable at times. 

The and and or are used primarily to do bit manipulation of 
individual bits in RAM, turning specified bits on or off. We'll see 
some examples of appMcations later in the book (We promise!). 
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CHAPTER 3 



Strings and Things 

(Subtitle: Never the Twine Shall Meet) 



In the last chapter we talked about the use and storage of nu- 
meric variables. In this chapter, we'll talk about another type of 
variable, the string variable. String variables are simply strings of 
alphabetic, numeric, and special characters that usually represent 
meaningful text data. Since there are operations that occur again 
and again in text processing, such as searching for given characters 
(such as a name) or comparing one string with another. Level II 
BASIC has a number of string functions built into it to make the 
job of processing string data easier. This chapter will describe what 
stiing variables are, how they are stored, and what types of opera- 
tions can be done with the built-in BASIC string commands. 



/HAVE > 



you BeeN 

( ■ STRINGIhlC ME 
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ASCII Strings 

In general, all strings are made up of ASCII characters. At least 
that was the original intent of strings, to provide a means to group 
keyboard or displayable characters, such as "YES", "NO", "12345F', 
"TRS-80", or ""o <>»»'; under a single variable name. By clever 
(some would say devious) means, the string definition can also 
include non-alphabetic, numeric, or special characters. (Well look 
at those a little bit later in the chapter. ) 

Legitimate names for string variables include any names that 
would ordinarily be used for any variables, suffixed by a "$". An 
alternate way to define a range of string variables is by a DEFSTR 
command which defines all variables in the given range to be 
strings. DEFSTR A-B would automatically define variables such 
as AA, AB, and BB as stiing variables, and they would be synony- 
mous with AA$, AB$, and BB$. 

The first question that comes to mind is "What is an ASCII 
character?" ASCII stands for American Standard Code for Infor- 
mation Interchange. A "standards" society has established certain 
standards for computers. It's certainly desirable to have all com- 
puters speaking the same language. In fact, many computers do 
speak the same language when it comes to common printable 
characters. That language is ASCII codes. 

ASCII is basically a seven-bit code. As we know from our com- 
prehensive and diligent study of Chapter 2 (Guard! Arrest that 
reader . . . ) , seven bits of data can define 128 different codes, from 
000 0000 to 111 1111. In ASCII, those 128 codes are used to repre- 
sent alphabetic, numeric, and special characters, and control codes, 
as shown in Table 3-1. The control-codes portion of ASCII from 
to 31 are somewhat non-standard from computer to computer. The 
15-code used in the TRS-80 to turn off the cursor, for example, is 
used in another computer to shift to upper case. 

The displayable portions of the ASCII codes used on the TRS-80 
are from code 32 through 127, as shown in the table. These are 
basically grouped into special characters ( space ) through ( / ) , nu- 
merics (0-9), special characters (:) through (@), upper case 

(A-Z), cursor controls (I" through ), and lower case (a-z and 

others). The standard TRS-80 has no provision for displaying 
lower-case characters. Lower-case characters, however, are still 
usable when output to a TRS-80 system printer such as the Quick 
Printer I or II. They simply can't be stored in the video display 
memory. 

The program shown below uses the INKEy$ function to get a 
one-character string from the keyboard and then display the key 
pressed in displayable form and its ASCII equivalent. Note that 
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Table 3-1. ASCII Codes 



Code Character 


Code 


Character 


Code 


Character 


Code 


Character 





32 


Space 


64 


@ 


96 


@ 


1 


33 


1 


65 


A 


97 


a 


2 


34 


" 


66 


B 


98 


b 


3 


35 


# 


67 


C 


99 


c 


4 


36 


$ 


68 


D 


100 


d 


5 


37 


% 


69 


E 


101 


e 


6 


38 


& 


70 


F 


102 


f 


7 


39 




71 


G 


103 


9 

h 


8 Backspace/erase 


40 


( 


72 


H 


104 


9 


41 


) 


73 


1 


105 


i 


10 Carriage return 


42 


* 


74 


J 


106 


i 


1 1 Carriage return 


43 


+ 


75 


K 


107 


1 
k 


12 Carriage return 


44 


, 


76 


L 


108 


i 


13 Carriage return 


45 


— 


77 


AA 


109 


m 


14 Cursor on 


46 




78 


N 


110 


n 


15 Cursor off 


47 


/ 


79 


O 


111 


o 


16 


48 





80 


P 


112 


p 


17 


49 


1 


81 


Q 


113 


q 


18 


50 


2 


82 


R 


114 


r 


19 


51 


3 


83 


S 


115 


s 


20 


52 


4 


84 


T 


116 


t 


21 


53 


5 


85 


U 


117 


u 


22 


54 


6 


86 


V 


118 


V 


23 32 character mode 


55 


7 


87 


W 


119 


w 


24 ♦-cursor 


56 


8 


88 


X 


120 


X 


25 -*cursor 


57 


9 


89 


Y 


121 


y 

2 


26 4cursor 


58 




90 


z 


122 


27 tcursor 


59 




91 


tor[ 


123 




28 Home cursor 


60 


< 


92 


lor] 


124 




29 Cursor to line start 


61 


= 


93 




125 




30 Erase to end 


62 


> 


94 


_» 


126 




of line 














31 Clear to end 


63 


? 


95 




127 




of frame 














Control Codes S 


peclal/Numerlct 


Upper Cote 


Lower 


Case 



the lower-case characters are read from the keyboard and appear 
in the proper ASCII code when the shift key is used (118 for 
lower-case v, for example, versus 86 for upper-case V), but that 
the video display can only display an upper-case V. 



100 CLS 

200 A$=INKEY* 

300 IF A$="" SOTO 200 

400 PRINT a 534,ASiASC(A$) 

500 GOTO 200 



dear screen 
* ' input character 

'back If no key input 

'print ker. ascii 
■'loop back for next chr 



From One to Hundreds 

The INKEYI function created a one-character string when a key 
was pressed. Level II BASIC allows us to handle up to 255 char- 
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LOCATION 

16384 



SYSTEM VARIABLES* 



PROGRAM 

STORAGE 

AREA 



SIMPLE VARIABLE 
STORAGE AR EA 



TOPOF 
MEMORY 



ARRAY 

STORAGE 

AREA 

__i 



FREE 
MEMORY 



I BUILDS 
1^ UP 

I BUILDS 
I DOWN 

^CONSTANT 
SIZE 



i STRING I 
i STORAGE! 
:: AREA I 



STACK AREA 



AREA RESERVED BY 
MEMORY SIZE? INPUF 



Figure 3-1. String storage area. 

acters in a string. Many of the strings we'll be working with will 
be less than 64 characters, since that size will conveniently fat on 
one display line. 

String variables are stored in RAM memory below the staclc, as 
shown in Figure 3-1. As a matter of fact, they are up above every 
other type of storage in the TRS-80. Because the BASIC inter- 
preter must know how much storage is required tor strings a 
CLEAR statement should be one of the first \hmgs that a BASIC 
program specifies when strings are to be used. Performing a 
CLEAR 2000, for example, clears 2000 bytes at the top of RAM 
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memory, just below any storage reserved by the MEMORY SIZE? 
input. If no CLEAR statement is specified, the BASIC interpreter, 
being a somewhat paranoid sort, goes ahead on the assumption 
you may throw in some strings anyway and reserves 50 bytes. 

Each string variable occupies one byte for each character of the 
string, plus an additional six bytes-3 for the string name (AZ$, 
AA$) and 3 for the length of the string and address. As in the 
case of simple variables (no slur intended on their mental abih- 
ties), the VARPTR command can be used to sneak a look at the 
variable in RAM. When VARPTR is used with a string variable, 
it returns an address that points to a block containing the infor- 
mation shown in Figure 3-2. 

A$ = "NOW IS THE TIME. " 
A = VARPTR (A$) 
A POINTS TO 



BYTE ^ 
BYTEl 
BYTE 2 



A$ LENGTH 


LS BYTE OF A$ LOCATION 


MS BYTE OF A$ LOCATION 



(BYTE 2) X 256 + (BYTE 1) 



POINTS TO STRING LOCATION 



W 



Figure 3-2. VARPTR use with strings. 

You might gain some insight into string storage by running the 
program below, which prints out the location of the string as it 
is input. 



1000 CLEAR 500 

1100 INPUT AS 

1200 B=VARPTR(AS) 

1300 C=PEEK(B) 

1400 D=PEEK(B+1) 

1500 E=PEEK(B+2) 

1600 PRINT •1ength=";c 

1700 PRINT "LOCATICiN=" ;E*256+D 

1800 GOTO 1100 



^clear strin9 space 
'input string 
'find location 
'9et length 
'Is address bvte 
' ms address bvte 
'Print length 
'print location 
^'loop to next input 
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Note how the location in RAM memory where the string is stored 
starts off at the top of memory and decrements down for each new 
input of A$. BASIC uses up all available string storage space (the 
CLEARed area) until it does not have more available, and then 
goes back to "clean up" and reshuffle the string data into the 
CLEARed area. 

This accounts for those mysterious delays that sometimes occur 
when one is working with large programs with many strings. The 
program has used up the string storage space, and the interpreter 
must reallocate string space to create new room. 

You can check the amount of free space that is available for 
strings by another BASIC string function, FRE$. It reports on the 
number of bytes available in the CLEARed area at any given time. 

90 CLEAR 50 'clear string space 

100 PRINT FRE(A$) 'print amount of free string space 

no INPUT A$ 'input a string 

120 GOTO 100 'loop back to print 

The variable used in PRE is any legitimate string variable name, 
used or unused. It is a "dummy" variable name and has no bearing 
on the report on the amount of all string space available. In the 
above case, the initial amount of string space available is 50 bytes. 
This 50 bytes is reduced by the length of the A$ entered. 

String Operations: Comparison and Concatenation 

Unlike numeric variables, string variables ^cannot be added, sub- 
tracted, multiplied, divided, ANoed, OKed, or have any of the other 
operations performed on them that we can normally do with inte- 
ger or single- or double-precision variables. Of course, the reason 
for this is that such operations are meaningless when we are con- 
sidering a sti-ing of ASCII values representing character data. The 
common operations that can be performed, however, are compari- 
sons and concatenation. Say what? Yes, the last term is another one 
of those terms of computer jargon whose definition is really very 

simple. 

Concatenation means to link together, as in a chain. (As a matter 
of fact, a hanging chain or other line forms a curve known as a 
catenary, hence the derivation— just thought you'd want to know. ) 
Two separate string variables can be linked together by the string 
concatenation operator "+" to form a single string variable. This may 
occur as many times as necessary (see Figure 3-3). 

A good example of concatenation uses the INKEY$ function to 
construct an ever-lengthening string variable. We used the INKEY$ 
variable earlier in the chapter, but let's discuss it a little more. 
INKEY$ looks at the keyboard for one instant in time. What in- 
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100 A$= "THIS IS A WIN" 

200 B$ = "EMONIC DEV" 

300 0$ = "ICE TO REME" 

400 D$ = "MBER CONGA" 

500 E$ = "TENATION!" 

600 F$ = A$ + B$ + C$ + D$ + E$ 




Figure 3-3. String concatenation. 

stant? We can see approximately how often INKEY$ scans the 
keyboard by the program below. This code continuously uses 
INKEY$ to look at the keyboard. If no key is pressed, a null string 
(0 length) is returned. A null string corresponds to " ". If a key 
is pressed, a one-character string made up of the keyboard char- 
acter is created. RUN the program and wait about ten seconds 
before pressing a key. The count of I is about 790, signifying about 
79 scans per second. This means that 79 times per second, the 
BASIC interpreter looks at the keyboard, at least for this code. 
Naturally, the statements 1 = 1+1 and IF A$=" " GOTO take some 
time to process, and the BASIC interpreter is not looking at the 
keyboard the entire time— perhaps it is looking at the keyboard V4 
of the time, as shown in Figure 3-4. However, the scanning rate 
is quite high and fast enough even for a prize-winning typist at 
150 words per minute ( 13 characters per second ) . 



2000 I =0 

2100 1=1+1 
2200 A*=INKEY* 
2300 IF A«="" GOTO 
2400 PRINT A». I 



'set coufft to 

r' start of 1 OOP 
'get character 
' 1 OOP unt i 1 chrctr 
'print char? count 



In any event, let's get back to the INKEY$ concatenation ( Edi- 
tor's note: Try not to digress— these readers' attention spans are as 
short as my Uncle Harry who . . .). We can do a continuous con- 
catenation as fast as you can type using the following code, which 
prints the length of the string and the string while concatenating a 
new one-character string from the keyboard. 
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LINE 


LINE 


LINE 




2100 


2200 
(INKEYS) 


2300 


J 





LINE 


LINE 


V— .► 


2100 


2200 
(INKEYS) 



LINE 
2300 



LINE 
2100 



LINE 

2200 

(INKEYS 



LINE 
2300 



! 
I 

t 



TOTAL TIME 

FOR LINES 

2100, 2200, AND 2300 



TIME FOR 
LINE 2200 



Figure 3-4. INKEY$ scan rate. 



3000 CLEAR 260 'clear string space 

3100 A=LEN<A») r'find string length 

3200 AS=A*+INKEYS I 'add neui char to string 

330B IF LEN(AS)=A GOTO 3200 ELSE PRINT LEN<ASIiA* 

3400 GOTO 3i00 '~'1oop for n>:t character 

Initially, 260 bytes are CLEARed for string space to permit a 
maximum string length of 255 bytes to be created. Variable A is 
set equal to the length of the A$ string, which is initially 0. (The 
LEN function returns the current length of a specified string.) 
Next, the INKEY$ function is used to concatenate any keyboard 
character input. If none is input, A$ is the same as before the 
INKEY$ operation, as is the LENgth. The new length of A$ is 



SO 



then compared to the old length A. If they are equal, no new 
character has been input, and a return is made back to the INKEY$ 
function. If they are unequal, a new character has been added, and 
the new length and string are printed with a GOTO to the state- 
ment to set A equal to the new length for the next comparison. 

Strings may be compared just as numeric variables may be com- 
pared. The same relational operators of < (less than), > (greater 
than), = (equal), <> (unequal), <= (less than or equal), or 
>= (greater than or equal) are used. 

It's easy to see how one string can be equal to or not equal to 
another, but what is the meaning of "less than," "greater than," 
and the others? The answer lies in ASCII codes. Comparisons are 
made on the basis of ASCII codes and their binary equivalents. 
From Table 3-1, we can see that a space is the "lowest-valued" 
ASCII character, while the lower-case characters are the highest. 
A string of "A C" (with A, space, C) will be "less than" "AAC," 
and a string of "?A" will be "greater than" "=A". In a case where 
strings are of unequal length but otherwise identical, the shorter 
string is less than the longer string. "AA" is less than "AA5", for 
example. The code below will let you investigate the comparisons 
of two strings. 



iaa 


CLEAR 500 






'clear string space 


200 


INPUT A$,B* 






-'input tiiio strinos 


300 


IF A$<B3i PRINT 


A$:" 


C" iB* 


'print if less than 


400 


IF A$=BS PRINT 


AS:"- 


=" ;b« 


'print if e-=iual 


500 


IF A*>B3i PRINT 


A3i:">"iB* 


'print if greater than 


600 


SOTO 200 






^ ' 1 OOP for input 



Printing the Unprintable 

No, this is not an excursion into "blue" books, although some of 
you had better watch your exclamations while running some of the 
routines presented here. We have seen how to convert from a single 
printable character into the equivalent ASCII code by the ASC 
("A") command, but how do we convert the other way, from a 
code to a character? The CHR$ lets us do just that. CHR$ is ex- 
tremely powerful since it lets us embed all kinds of unusual char- 
acters in a character string, characters that simply can't be input 
from the keyboard! The argument of CHR$ is a numeric value from 
to 255, or an expression that is equivalent to those values. The 
code below displays all characters from 32 to 191. The ASCII codes 
from 192 to 255 are not printed, as they are tabs for to 63 spaces 
and scroll the display off the screen. The codes from to 31 are 
also not displayed, as some of them cause screen clearing, line 
clearing, and so forth. 
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1000 CLS 

1100 FOR 1=32 TO 171 

1200 PRINT CHRiEd) ; 

1300 NEXT I 

1400 GOTO 1400 



jcreen 
codes 



p'ascii codes 
I 'print character 
*" ' 1 OOP for next 
loop here for display 



The interesting thing about the display is that not only are char- 
acters displayed that can't be generated from the keyboard (such 
as I, ^, and -^ ), but the graphics character codes are also displayed. 
It is possible, then, to incorporate graphics character codes from 
128-191 into a character string! This is an exciting concept because 
strings are printed very rapidly, and we may be able to use this to 
advantage to get "high-speed" graphics. We'll discuss this concept 
further in Chapter 5. 

The CHR$ function can be used to compare any non-printable 
character in the program. A backspace, for example, does not re- 
sult in a displayable "*-", but rather is converted into a code of 8. 
We can look for that code using a CHR$ (8) function: 



2000 ES=INKEYS 

2100 IF B»="" GOTO 2000 

2200 IF B$<>CHR$<B) GOTO 2500 

230B PRINT "BACKSPACE" 

2400 GOTO 2000 

2500 AS=A«+B« 

2600 PRINT AS 

2700 GOTO 2000 



'get character 
' trv again if null 
'go if not bs 
'backspace found 
'get next character 
" concatenate 
'print current string 
^~'9et next character 



Left, Might, Left, Right, Mid, Right . . . 

We're allowed to link or concatenate two strings, but are not al- 
lowed to truncate a string into a shorter string directly. How do we 
then access parts of strings? There are several approaches to a 
problem such as this. The ways in which Level II RASIC ap- 
proaches it are from the right, from the left, and from the middle. 
( I know, I know ... 7 just couldn't resist. ) The three methods are 
implemented by the LEFT$, RIGHT$, and MID$ functions. They 
allow all or a portion of a string variable to be accessed starting 
from the right or left, or by taking a portion out of the middle, as 
shown in Figure 3-5. 



CHARACTER 
1 



CHARACTER 
40 



A$ = "NOW IS THE TIME FOR ALL GOOD PROGRAMMERS" 



LEFTS (A$,10) 
GETS LEFT 10 
CHARACTERS 



MIDI (A$,17.7) 
GETS MIDDLE 
7 CHARACTERS 
STARTING WITH 
CHARACTER 17 



RIGHTS (A$,9) 

GETS RIGHT 

9 CHARACTERS 



Figure 3-5. Accessing strings. 
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The LEFT$ function gets the first n characters from the left of 
the string variable. B$ = LEFT$("A MAN A PLAN A CANAL 
PANAMA",5) would set B$ equal to "A MAN". 

The RIGHT! function gets the last n characters from the right 
of the string variable. B$ = RIGHT$("A MAN A PLAN A CANAL 
PANAMA",5) would set B$ equal to "ANAMA". The following rou- 
tine shows how this can be used to retrieve characters from the 
right or left. 



3000 A!E="A MAN A PLAN A CANAL PANAMA" 

310B FOR 1=1 TO LENiASl 

3200 PRINT LEFT$<AS.I) 

3300 FOR J=0 TO 50 

3400 NEXT J 

3500 NEXT I 

3600 FOR 1 = 1 TO LEN(Ai6) 

3700 PRINT TAe(LEN(AS)-I) ;RIGHT$(A3i, I> 

3800 FOR J=0 TO 50 

3900 NEXT J 

4000 NEXT I 



='a 


indroFT 


e ' 




_ 


o u t e r 


loop 






ppint 


fro III 


left 




p' inner 1 c 


OP 




^'for 


del a 


V 


i_ 


1 ar-ger- 


and 


larger 


_ 


outer 


} OOP 






pr-int 


from 


r- 1 9 h 1: 




f ' inner 1 .: 


OP 




l-'for 


dela 


r 


'- 


1 ar9er 


and 


1 arger 



The MID$ function is used to take a portion of a string out of 
the middle. MID$ specifies a string variable, a starting location 
(from the left), and the number of characters to be retrieved. B$ 
= MID$("A MAN A PLAN A CANAL PANAMA", 10,5) would 
create B$ = "LAN A". The following code creates two strings, one 
made by concatenating single characters starting from the left, and 
the other made by concatenating single characters starting from the 
right; both use the MID$ function. 

50 CLEAR 400 -clear string space 

100 A«="A MAN A PLAN A CANAL PANAMA" 'read it sdrauikcab 

200 FOR 1 = 1 TO LEN(A») p-lf.c.p for mid 

300 BS=MID»(A«t1,1)+B« 'from left 

400 CS=MID$<At,LEN(A*l-H-l. D+CS 'from right 

500 NEXT I "-.^o^j.^^.^^ 

600 PRINT B* 'print left string 

700 PRINT CS 'print right string 

The STRINGI String 

One of the remaining sbing functions that we haven't mentioned 
yet is the STRING$ function. With STRING$, you can create a 
string of identical characters. The format of STRING$ is STRING$ 
(n,"c"), where n is a value from to 255 and "c" is either a string 
or value (or expression). The character or value represented will 
be replicated n number of times. For example, PRINT STRING$ 
(20,"#") prints 20 pound signs and PRINT STRING! (32,63) prints 
32 question marks (63 is the ASCII code for "?"). 

The value in STRING$ may be any value from to 255, includ- 
ing graphics characters. (The graphics potential for STRING! is 
discussed in Chapter 5. ) STRING! is especially handy for printing 
headings, filling in display fields with fill characters, or filling in 
strings with fill characters. 
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Numeric to Strings and Back Again 

We have two more string functions to investigate before trying 
our hand at a generalized input routine, cursor control, text edit- 
ing, and some other functions. If you'll bear with us (Guard, that 
gun is not necessary . . .), we'll complete this discussion of string 
functions by looking at two powerful functions, STR$ and VAL. 

STR$ converts a given numeric value or expression into a string. 
The string can then easily be edited and processed for printing or 
display. 

PRINT STR${12.34) 

for example, converts the single-precision variable 12.34 into the 
string variable " 12.34", six characters long, and 

PRINT STR$(lE-06) 

converts the single-precision variable IxlO^" into the string vari- 
able " IE— 06", six characters long. A leading blank appears before 
the numeric value in the string to allow for a possible minus sign 
as in 

PRINT STR$(-999P) 

which would generate "—9999", five characters long. 

VAL operates in reverse fashion from STR$; it converts a string 
variable or expression into a numeric value— eVALuates it. The 
string variable must be either numeric characters, a decimal point, 
or exponent (E or D). Evaluation stops on the first (non-E or D) 
alphabetic or special character encountered. 

Expression Result 

VAL("12.34") 12.34 

VAL("12E-06") T.2E-05 

VAL("9999.9999") 9999.9999 

VAL("12D-06") 1.2D-05 

VALC'TEXTIOO") 

VAIC'IOOTEXT") 100 

Note that if the string starts with a non-numeric character, it 
evaluates as zero. 

VAL can be used to convert a string of numeric data to a more 
compact numeric variable form. This saves memory for large 
amounts of numeric data, but more importantly, it drastically re- 
duces the amount of processing time required. 

A Thousand Cursors Upon You, Effendi! 

Knowing what we now know about the manipulation of strings, 
large and small, it .should be a simple matter to produce some use- 
ful general-purpose text-handling routines. Some of the things we'll 
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be discussing in the remainder of this chapter will be cursor con- 
trol, generalized string inputs, and text editing. 

Just how do we manipulate the cursor? If we look at Table 3-1 
again we see that there are indeed cursor control characters that 
can be output to the screen. These are backspace cursor (24), ad- 
vance cursor (25), down cursor (26), up cursor (27), home cursor 
to character position 0, hne (28), and move to beginning of line 
(29). In addition to these, we can turn the cursor on (14), and ofiF 
(15). 

As an example of how we can implement these cursor codes, look 
at the routine below. It moves the cursor to the home position 
(CHR$(28) ), clears the screen (CHR$(31)), moves back to home 
(CHR$(28)), and turns on the cursor (CHR$(14)). The cursor is 
then moved in spiral fashion until it retreats to the screen center. 



[' Upper 
'move 

' 1 OOP 

r-ri 

mo 

'-•}o 



to right 



" ' right side 
ove domn 



1000 PRINT CHR»(2S);CHR»<31)! 'home and clear screen 

1100 PRINT CHR»(28) ;CHR»(14) ! 'home and turn on cursor 

1200 H=63 'initial horizontal 

1300 V=14 'initial vertical 

1400 FOR 1=1 TO H 

1300 PRINT CHRS<25) : 

1600 NEXT I 

1700 FOR 1 = 1 TO V 

1800 PRINT CHRS(26) ! 

1900 NEXT I 

2000 V=V-1 

2100 H=H-1 

2200 FOR 1=1 TO H 

2300 PRINT CHRS<24) ; 

2400 NEXT I 

2500 FOR 1=1 TO V 

2600 PRINT CHR3;(27)! 

2700 NEXT I 

2800 V=V-1 

2900 H=H-1 

3000 GOTO 1400 



'adjust vertical 
'adjust horizontal 
* bottom 
Tiove to left 



r ' hot 
' mov 
I- 'loo 
r ' left s 
I 'move u 

' 1 OOP 



left side 



'adjust vertical 
'adjust horizontal 
'loop for next spiral 



The above code is more than a little showy and not too useful 
(unless you're a spiral freak). However, it does show that we have 
complete control over the cursor and related screen control char- 
acters in our BASIC programming. We can use this fact to advan- 
tage in writing a good generalized input routine. 

The Universal Gee Whiz Input 

This routine is meant to exercise our string capabilities, but also 
to provide a general-purpose keyboard input routine. On input, it 
is desirable to have a routine that will accept string input from any 
of the 1024 input positions. A "fill" string of blanks or an existing 
character string such as "MM/DD/YY" should be available to ini- 
tialize the input area. Another nicety is the ability to move the cur- 
sor within the field to any position to permit modification of previ- 
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CURSOR READY FIELDS CONTROLLED 
FOR INPUT BY CURSOR 




ORDER DRAWN 

BY GRAPHICS 

(SEE CHAPTER 5) 



Figure 3-6. Form fill-in. 



ously input or existing text. Also, control characters that might 
create ambiguous conditions, such as down cursor, must be ignored. 

A generalized input routine such as this allows easy form fill-in 
as shown in Figure 3-6. The form is made up of several fields, each 
of which may be controlled by the input routine. Another example 
would be modification of existing strings under cursor control 
rather than by retyping the entire string. 

The program shown in Figure 3-7 provides all of these features. 
The subroutine is CALLed with string variable ZA$ containing the 
fill string to be used. The "@" location for the string is contained 
in variable ZC (0-1023). When the subroutine is CALLed, the fill 
field will be printed at the spot designated, and data may then be 
entered from the keyboard. The fill field must be all on one line 
for proper operation. The cursor may be moved without destroying 
the data by "<-" and "-^". The cursor may not be moved past the 
start of the field or past the end of the field. When the data has 
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40 REH CLEAR SCREEN AND CALL SUBROUTINE 

50 CLS 

100 ZA$="«*************" 

200 ZC=512 

300 GOSUB 20000 

400 PRINT ZA!t 

500 SOTO 40 

19000 REM PRINT FILL FIELD AND BACKSPACE CURSOR TO START 

20000 PRINT aZC,2A«;CHR$(14) ; 

20010 FOR ZF=1 TO LENiZASl 

20020 PRINT CHRS(24)! 

20030 NEXT ZF 

20035 REM SET CURSOR POSITION TO 1 AND GET KEY PRESS 

2B040 ZS=1 

2B050 ZHS=INKEY$ 

20060 IF ZH«=" " GOTO 200S0 

20065 REM TEST FOR LFT CURSORiRT CURSOR, ENTER. AND VALID CHAR 

20070 IF ZH$=CHR»<8) OR ZHS=CHR*<'?) OR ZHS=CHR»<13) GOTO 20080 

20075 IF 2H3i<CHRS(32) GOTO 20050 

20080 IF ZH*<>CHRi(B) GOTO 20120 

20085 REM LEFT CURSOR ROUTINE. DONT GO PAST START 

20090 IF ZG=1 GOTO 20050 ELSE PRINT CHRS(24)1 

20100 ZG=Ze-l 

20110 GOTO 20050 

20120 IF ZH*<>CHR$(9) GOTO 20160 

20125 REM RIGHT CURSOR ROUTINE. DONT GO PAST END 

20130 IF ZS>=LEN(ZA!5) GOTO 20050 ELSE PRINT CHR«<25i; 

20140 ZG=ZG+1 

20150 GOTO 20050 

20160 IF ZH$<>CHR!t(13) SOTO 20190 

20165 REM ENTER ROUTINE. PRINT FINAL STRING AND RETURN 

20170 PRINT azC,CHR$(15) ;ZA« 

20180 RETURN 

20185 REM VALID CHARACTER ROUTINE. PRINT CHARACTER, ADJUST CURSOR 

20190 ZG=ZG+1 

20200 IF ZS>LEN(ZA*)+1 PRINT CHR$(24): 

20210 IF ZG>LEN<ZAS)+1 ZG=ZG-1 

20220 PRINT ZH*! 

20230 ZA$=LEFT»(ZA$, (ZG-2) J+ZH$+RIGHTS < ZA$, LEN< ZAS )-ZG+l i 

20240 GOTO 20050 

Figure 3-7. Universal Gee Whiz Input. 

been properly input, the "ENTER" key causes a return to the call- 
ing program. The subroutine is shown with a short driver program 
illustrating its use. For maximum input speed, this code should be 
compressed by removing REMark statements, using multiple state- 
ment lines, and locating it with "low-valued" line numbers. 

Within the subroutine, ZG is used to mark the current cursor po- 
sition within the field. ZG vidll always contain a value of 1 to LEN 
(ZA$). ZG is adjusted for left cursor (8), right cursor (9), or for 
any new character. Control characters otiher than 8, 9, or ENTER 
(13) are ignored. Whenever a new character is entered, the sub- 
routine finds the portion of the field string left of the cursor, con- 
catenates the input character ZH$, and concatenates the portion of 
the field string right of the cursor to create a new string equivalent 
to the display on the screen. This string is passed back to the call- 
ing code as the updated string and is also left on the screen after 
the cursor is turned ofiF and the display restored. 

In spite of the heading, this input routine does not contain all 
the "bells and whistles" that could be put in. However, it should 
sufiice for many applications. 
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Text Editing 

Strings are a natural format for text editing applications pro- 
grams. Text editing is also called word processing. Text editing 
allows a user to manipulate text for manuscripts, letters, and other 
appearance-oriented printing. A comprehensive text editor provides 
for deletion and insertion of characters, words, paragraphs, and 
blocks, automatically justifies (creates an even margin), counts the 
words in a block, and performs other sophisticated functions. We 
can't create a complete text editor in this chapter, but we can illus- 
trate some of the ways a BASIC text-editing program could be im- 
plemented. 

Three common operations in text editing are searching, deleting, 
and inserting. Most text editors allow a user to search a string for 
a given string contained within it. We can make full use of the 
comparison capabilities for string variables to implement a search. 
The code in Figure 3-8 inputs a string of text that creates a text 

1000 CLS 'clear screen 

1010 CLEAR 10BB -clear string space 

1B2B INPUT "TEXT BASE:";A* 'input text to search 

1030 INPUT "SEARCH STRING" !B« 'input string to find 

1040 CLS 'clear screen 

1050 PRINT a 512>AS 'print string to be searched 

1060 FOR 1=1 TO LEN(A$)-LEN<BS)+l p' setup loop for search 

1B7B IF MID*(A3i. IiLEN(B»)l=B* SOTO 1105 | 'go if string found 

IBBB NEXT I "-'continue search 

I09B PRINT B«;" NOT FOUND" 'string not found here 

1100 GOTO 1100 'loop here 

1105 1=1-1 'adjust for computation 

1110 PRINT CHR3i<14) !CHR«(28)! 'turn on cursor and home 

1120 FOR J=B TO 7+INT<I/64) r-'setup loop to find line 

1130 PRINT CHR3i(26)! 'down cursor 

1140 NEXT J *- 'continue til] line fnd 

1143 IF I-INT( I/64)«64=0 SOTO 1180 'go if character position 

1150 FOR J=l TO I-INT(I/64)»64 p'setup loop to find char 

1160 PRINT CHRS(25): 'advance cursor 

1170 NEXT J "-'continue till char- fnd 

1180 GOTO HBO 'loop here at end 

Figure 3-8. String search operations. 

base and then inputs a search string to be found within the text 
base. Obviously, the search string must be shorter than the text 
base. If the string is found, the cursor is moved to the position of 
the string. The cursor movement portion of the program has to con- 
sider the number of lines to move down (7 to get to @ 512 plus 
INT (1/64) to get to the proper text line [there are 64 characters to 
a line] ) and the number of positions to the right after the proper 
line is found (I-INT(I/64) ). 

Deletions of characters within text normally cause the remaining 
text to "snake up" into the space left by the deleted characters, as 
shown in Figure 3-9. BASIC code to implement the delete function 
(not shown) might reconfigure the string with the current cursor 
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CURSOR POSITION 

FOR nFi FTiriN DELETIONS OF CHARACTERS WITHIN 

ruK utLi:iiuis^^^j^gjg^^Q|^j^^i_i_Y g^^jgg ^j^g ^g^^i^ pipgj DELETION 

ING TEXT TO 'SNAKE UP' INTO TH 

DELETIONS OF CHARACTERS WITHIN 

TEXT ORMALLY CAUSE THE REMAINI SECOND DELETION 

NG TEXT TO 'SNAKE UP' INTO THE 

DELETIONS OF CHARACTERS WITHIN 

TEXT RMALLY CAUSE THE REMAININ THIRD DELETION 

G TEXT TO 'SNAKE UP' INTO THE 

Figure 3-9. Deleting characters in text. 

character deleted and print it at the same screen position. The code 
could insert by reconfiguring the string ■with an insert character 
inserted at the current cursor position and "snaking" the string 
down as characters are inserted. These operations are shown in 
Figure 3-10. 

1. INITIAL TEXT 

THIS IS A SAMPLE OF TEXT 

\ 
CURSOR 

2. PRESSING "4" DELETES AT CURRENT CURSOR 
POSITION. A NEW STRING IS CONSTRUCTED FROM 
THE RIGHT AND LEFT PORTIONS OF TEXT. 



THIS IS A SAMPLE OF TEXT 



/ 1 \ 

LEFTS CHARACTER RIGHTS NEW STRING = 
PORTION TO BE DELETED PORTION LEFTS -f RIGHTS 

THIS l_A SAMPLE OF TEXT 

3. PRESSING A NON-CONTROL KEY INSERTS THE 
CHARACTER AT CURRENT CURSOR POSITION -f 1 
SO THAT "TEXT" FLOWS TO LEFT. 



THIS IS A SMPLE OF TEXT 



/ / I 

LEFTS CURSOR RIGHTS NEW STRING = 

PORTION PORTION LEFTS + CHARACTER 

FOR INSERT + RIGHTS 

THIS IS A SAMPLE OF TEXT 
Figure 3-10. Text editing deletes and inserts. 
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This code might perform two functions— delete and insert, along 
with cursor positioning. The "^" and "-*" keys would position the 
cursor anywhere along the text string. Pressing "t" would delete 
the character at the current cursor position and snake the remain- 
ing text up. Pressing any non-control key would insert text at the 
current cursor position and snake the text down. 

The biggest problem in this application is cursor positioning. The 
cursor must be referenced to a known starting point and adjusted 
not only right or left, but up and down as well for line starts and 
ends. For each delete, a new string might be constructed from the 
left and right portions of the current string with the character re- 
moved at the current cursor position. For each insert, a new string 
might be constructed from the left and right portions of the current 
string with the character at the current cursor position embedded 
between the two strings; the cursor could then be moved over one 
position to the right so that the text is built from left to right. 



Another Approach 

The implementation of the text editing application above used 
strings to handle insertions, deletions, and other text-editing func- 

START OF 
TEXT AREA 



VIDEO 

DISPLAY 

"WINDOW- 



END OF RAM 
TEXT AREA 





QOIUJFJDLALKD 
HELP 1 AM BEING HELD 
PRISONER IN RAM Ei 
JKFDLALSKDIEURP 




THIS IS TEXT DISPLAYE 
D ON SCREEN JKSOPX 
ZABLNOQSVHKDJ 
SLIEOWIEJDJDLSKD 




JKFKFKFKFKFKFK 
AWOMANISAWOMAN 
BUT A TRS-80 IS A EIW 
EIWOEiFJDKSLSLDKFJ 



SCROLL 
UP TEXT 



SCROLL 

DOWN 

TEXT 



Figure 3-11. Text editing using display memory. 
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tions. Another approach to the problem is to treat the entire video 
display memory as several huge strings. The screen is actually a 
memory that will store displayable (and graphics) characters, so 
it is an excellent vi'ay to implement such an application. Insertions 
of characters can be handled by moving blocks of screen memory 
down from the current cursor position to the end of screen memory 
(16383). Deletions can be handled by moving a block of screen 
memory up. The screen represents a "window" of a much larger 
text area in this case, with the window scrolling up and down to 
allow display and text editing functions on various portions of the 
text ( see Figure 3-11 ) . We'll discuss display applications more fully 
in Chapter 5, and the reader may be able to get a better picture 
(pun intended) of the types of things that can be done in working 
with the display memory. 
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CHAPTER 4 



lor Latest Report Indicates 



In this chapter, we'll provide some information about printing 
reports on the screen and on the system line printer. We'll also dis- 
cuss in detail the use of PRINT USING, a powerful statement for 
formatting string and numeric values. 

Why do we want to format reports? First, there's the aesthetic 
aspect. Nobody likes to see sloppy, uncolumnated reports coming 
out of a powerful computer system. The processing involved may 
be spectacular, but the effect of a cluttered report may be disas- 
trous. (Or vice versa. I once saw several vice presidents of an air- 
craft manufacturer literally enthralled by meaningless data nicely 
printed on a system they had ordered that wasn't quite ready.) 
Secondly, to produce useful reports, displays, and other graphics,_ 
the programmer is forced to define some format for the report to 
follow with pagination (new pages), columnization (putting data 
in proper columns), and menus (lists of choices to prompt the 
user). 

One From Column A and One From Column B 

The PRINT statement is easy to understand. A PRINT statement 
with a single item and no comma or semicolon at the end prints 
the item at the start of the next line on the screen and then moves 
the cursor position to the start of the next line as shown in Fig- 
ure 4-1. 

100 PRINT 4.55 'print 4.55 and move to next line 
200 GOTO 200 'loop here 
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Figure 4-1. Simple print action. 



CURSOR 
POSITIONED 
HERE AFTER 
PRINT OF 
4.55 




The data printed in this first case is -bi.BSb; because the number 
was a positive number, a blank is printed in place of a "+" sign. 
If the number is a negative number, such as —8.95, then the nega- 
tive sign is printed, followed by the magnitude of the number. In 
both cases, the number also has a trailing blank in addition to the 
leading blank or negative sign. You can see this by the code below, 
which uses a semicolon to specify that the cursor is not moved to 
the next line, but remains where it is after the print. The cursor in this 
case normally must be imagined, as it is not active during execution 
of the program unless we turn it on in the program. We've turned 
it on before doing the PRINT, using the cursor-on code (14) that 
we discussed in Chapter 3 ( see Figure 4-2 ) . 

100 PRINT CHR$(14) 'turn on cursor 

200 PRINT -4.5;4.5; 'print two values 
300 GOTO 300 'loop here 

Notice that the format is — 4.5Bb4.5; each print is five character po- 
sitions on the screen, one for the sign, three for the "4.5," and a 
trailing blank. 

The unfortunate thing about printing in this fashion is that vari- 
ables are not fixed-length. When variables are printed, leading and 
trailing zeroes are always suppressed as in the display from this 
code 



100 FOR 1=0 TO 1000 
200 PRINT I1-1.1; 



300 NEXT L 'continue 



'loop 1001 times 

'print I to the 1.1 power 



How do we go about columnating data in this simple case? One 
way to do it, of course, is by using a comma instead of a semicolon 
to tab to the next print zone. The print zones on the video display 
are positions 0, 16, 32, and 48, and using a comma after each print 
item will print data in four nice, neat little columns. 



100 FOR 1=0 TO 1000 

200 PRINT Ifl.l, 'use tab on prints 

300 NEXT 
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CURSOR POSITION 
AFTER PRINT 



Figure 4-2. Variable printing. 

This is definitely an improvement, but there are still problems 
with the appearance of the data— namely, the decimal points don't 
line up. There are other problems with this type of columnization, 
also. The world is not always a four-column world, as evidenced 
by the new tax-return formats. Sometimes, we would like to 
squeeze eight columns of data onto the screen, especially if we 
know that the variables will be limited to six digits plus sign and 
trailing blank. And how about the case of dollars and cents data? 
We would like to see the .00 cents displayed instead of being sup- 
pressed in cases when we're dealing with the almighty dollar. 

The first problem of additional columns may be partially solved 
by a PRINT TAB statement. PRINT TAB moves the cursor posi- 
tion to a specified character position along the line from 1 to 64. 
PRINT TAB may be used to produce a display of more than the 
four print-zone columns by tabbing over to the next column after 
printing a data item. This works, providing the length of the data 
item is known to be less than the width of the column plus 2. 
Suppose, for example, the data items to be printed are three digits. 
Adding one trailing blank and one leading blank defines a column 
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of five characters and a total of 12 columns, as shown in the code 
below and in Figure 4-3. 



100 FOR 1=1 TO 60 STEP 5 
200 PRINT TAB(I)!123; 
300 NEXT 3 
400 PRINT 
500 SOTO 100 



r 'tat. 5.101 15i . . . 
I 'print dummy value 
•- 'loop 
1 me feed 
■'next set 



Here we've "dummied up" the value to guarantee that we have 
three digits each time. When we use values that may be any num- 
ber of digits from 1 to 4, we get the same problem as previously: 
columns that are not right justified, as shown in Figure 4-4. 



1000 FOR 1=1 TO 60 STEP 5 
11B0 PRINT TAB<I );RND('?99) ! 
1200 NEXT I 
1300 PRINT 
1400 GOTO 1000 



■ r 'tab 5, 10. 15.. . . 

I 'print tab and 1-3 char= 

' 1 OOP 

' 1 ine feed 
'next set 




61236 
TRAILING OR LEADING SPACE 



Figure 4-3. Columnating example 1. 
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MANY COLUMNS CONTAIN 

ENTRIES THAT ARE NOT 

"RIGHT JUSTIFIED" 



Figure 4-4. Columnating example 2. 

There's No Justification for This . . . 

How do we solve the problem of justifying data? Since we can't 
predict the number of digits in a variable beforehand, we must 
somehow find the length before printing. For string data, this pa- 
rameter is easy to find as we have the LEN function. But wait! 
Don't we have the ability to convert numeric data to string data? 
{You really should have read Chapter 3. Guard, get that name and 
address . . .) Yes, the STR$ function converts a numeric variable 
or constant to a string. If we convert to a string and then use the 
LEN function to find the string length, we can handle justification 
of columns. Let's see how it works. 
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2000 


INPUT "JUSTIFY Y/N";AJi 


'input Justify action 


2100 


FOR 1=1 TO 5S STEP 6 


r- ' tab 1,7, 13, . . . 
1 'get i-A digits 


2200 


A=RND(?<?99) 


2300 


IF AS="N" THEN PRINT TABCI) 


;a; else goto 2500 


2400 


GOTO 2B00 




'for next loop 


2500 


B«=STR$(A) 




'convert to str-in'3 


2600 


C=LEN(B3il 




'find length 


2700 


PRINT TAB( I+5-C) !B*: 




' tab and print 


2800 


NEXT I 




■- ' loop 


2900 


PRINT 


'get next ! ine 


3000 


GOTO 2100 


'again 



The program above first asks for a decision on justification. If the 
ans'wer is "N", then ten columns of 1-4 digits are printed as we have 
been doing— each variable is printed with a leading blank (for 
sign ) and a trailing blank plus 1 to 4 digits, making a column entry 
three to six digits. If the answer is a "Y", then the 1 to 4 digit value 
from RND(9999) is converted to a string by STR$(A). Note that 
STR$ converts the numeric value with a leading blank for positive 
values (or a minus sign) and no trailing blank. The length of the 
string is therefore 2 to 5 digits. The tab position to be used is the 
extreme left of the column for a five-character string 

TAB=:I+5-5=I, 

three positions over for a string of 2 digits 

TAB=H-5-2=I+3, 

or intermediate positions for strings of four or three characters ( see 
Figure 4-5). Our display in this case definitely gets an "A" for 
neatness. 

Dollars and Cents 

Changing a numeric to a string by means of STR$ may be done 
for all types of numeric data so that the length of the field may be 
computed before printing. When the numeric data includes a deci- 
mal point, the decimal point will also be converted. 

100 PRINT STR$(nT.77) 'convert and print 

will print "111.77". However, we still have the same problem with 
the decimal point! If the variable is 111.5000, it will be printed as 
"111.5" rather than a dollars and cents value of 111.50. Also, 111.00 
will be printed as "111" and 111.234 will be printed as "111.234"! 
How do we make cents out of such a value? One way to accomplish 
this is to scan the resulting stiing variable after the STR$ conver- 
sion for the decimal point and to add a decimal point and trailing 
zeroes as required. The following subroutine takes an input vari- 
able ZZ and converts it to a dollars and cents format in string va- 
riable ZZS. 
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1BO0B ZZ*=STRS(ZZ! 

10010 FOR 1=1 TO LEN(ZZ«1 

1B020 IF HIDS(ZZ«, I. 1)=". " aOTO 1B060 

10030 NEXT I 

10040 ZZ«=ZZ»+".B0" 

1B050 RETURN 

10060 IF l=LEN<ZZ$)-2 RETURN 

10070 IF I<>LEN(ZZ»)-1 GOTO 10100 

1008B ZZ«=ZZ«+"0" 

10090 RETURN 

101B0 ZZ$=LEFT»(ZZ«.H-2) 

10110 RETURN 



'convert to string 
■ ' 1 ook for dec pnt 
found 



CI ook 
•go If 
■loop 



'not fnd-add cents 
'return to calling prog 
'return if #«.»# 
'go if not #«.# 
'convert to ##.## 
'return to calling prog 
'use onlv 2 cents digits 
'return to calling prog 



There are five cases in the above subroutine. ZZ may be con- 
verted to a string of the form ##, with no decimal point and no 
characters for the cents. In this case, the search for the decimal 
point using MID$ is not successful, and a new ZZ$ is created by 
adding ".00" to the original string. The second case occurs when 




EVERY ENTRY IS 
RIGHT JUSTIFIED 



Figure 4-5. Use of STR$ function for columnating. 
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ZZ$="##.##", a string with a decimal point and two cents char- 
acters. In this case (I=LEN(ZZ$)-2), nothing must be done and 
a RETURN is made. The third case occurs when ZZ$="##.#". 
In this case (I=LEN(ZZ$)-1), only a "0" needs to be added. 
The fourth case occurs when ZZ$="##.###. .", a string of more 
than two cents digits. In this case, we must shorten the string by 
talcing only the first two cents digits and taking the left-hand side 
of the string up to the decimal point plus two digits. Three notes 
on the technique used above: 

1. The case "##." never occurs because the decimal point would 
always be deleted. 

2. The technique of truncating the digits to the right is not neces- 
sarily the best way to handle the fractional cents. Millionaire 
programmers have been produced when such fractional cents 
have gone into other checking accounts. 

3. The code above could be replaced by two statements. ( ExtraJ 
Extra! Writer Mobbed by Angry Readers!) 

All right! I know that you're angry with me for going through the 
code above when it could have been replaced by two instructions. 
However, I just wanted to show you how powerful that one instruc- 
tion was. The instruction is . . . (may I have the envelope please?) 



PRINT USING! 
The entire code above could have been replaced by 

10000 PRINT USING "####.##";ZZ 'print dollars, cents 
10010 RETURN 'return 

In the PRINT USING statement above, the "#" characters de- 
fined a digit position for a numeric field, and the decimal point 
defined the decimal point location within the field. If the value in 
ZZ had more than two digits to the right of the decimal point, they 
would have been "rounded off' to produce only two digits; if the 
ZZ value had fewer than two digits to the right of the decimal 
point, then the remaining digit positions would have been filled 
with zeroes. If the numeric value had fewer than four digits to the 
left of the decimal point, the remaining positions would have been 
filled with spaces. Neat, eh? 

Let's look at some of the other capabilities of the PRINT USING 
statement. Another "field specifier" character that may be added in 
the definition string is a comma. Since the PRINT USING is used 
primarily for accounting-type applications, an obvious use of a 
comma is to provide the comma for large dollar amounts. 
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50 INPUT A 'provide input 

100 A$ = "###,###.##" 'define string 

200 PRINT USING A$;A 'print using A$ string 

300 GOTO 50 'return to input 

The PRINT USING statement above should handle many of the 
reader's weekly paychecks and provide a printout of such amounts 
as 1,232.77, 66,327.00, and 121,067.99. The comma and decimal 
points may be inserted anywhere within the string, but such string 
field specifiers as #.#,.## are not too meaningful and may confuse 
the BASIC interpreter. 

How about dollar signs? I'm glad you asked. One dollar sign 
used as a field specifier will cause a dollar sign to be printed at the 
left with intervening print positions filled with spaces. PRINT 
USING "$####.##" will enable printouts such as $1000 00, 
$bbB1.23, and $feb77.79, $BW50.36. Two dollar signs used as field 
specifiers will float the dollar sign and put it directly before the 
fi/st digit printed. PRINT USING "$$####.##" produces print- 
outs such as $1111.77, $13.24, $1.77, and $0.34. Note that dollar 
amounts less than one dollar are printed with a leading for the 
dollar amount in both the floating and non-floating dollar-sign case. 

Have any of you ever altered your paychecks to increase your 
weekly wage— no, of course not (Guard, let's get those names . . .). 
One safeguard against such action is the use of asterisk characters 
before the printing of the dollar amount. When a '*°$ field specifier 
is used in PRINT USING, asterisks will occupy all field positions 
before a floating dollar sign. PRINT USING ""*$####.##", for 
example, will produce amounts such as '""$11.11, <* "$1000.99, 
'$10000.10, and $10000000. Note that the maximum amount that 
"»«$####.##" can hold is $999999.99 with seven characters in- 
cluding "$" to the left of the decimal point. 

Accounting type information sometimes uses a trailing minus 
sign after the amount. When the field specifier "— " is used at the 
end of a field, a minus will be printed if the amount is negative. 

100 A$ = "#####.##-" 'define string 

200 PRINT USING A$;A 'print using A$ 

prints 22.23- when A is negative or 22.23 when A is positive. 

When an initial + or - sign is required, a -|- sign placed at the 
beginning of the field results in a "+" character for positive num- 
bers or a "— " character for negative numbers. PRINT USING 
+##.## produces 4-12.22, 4-1.22, 4-0.22, -12.22, -1.22, or -0.22. 

The % and ! field specifiers are used to denote string fields that 
must be printed. When the first character of a string must be 
printed, "!" is used. 

TOO A$="1234" 'string 

200 PRINT USING "l";A$ 'print first character 
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Table 4-1. PRINT USING Field Specifiers 



Specifier 


Description 


PRINT USING A$;N 


A$ 


N 


Result 


# 


Numeric field 


### 


13 


•613 






### 


2 


*62 






### 


-2 


^-2 




Decimal point 


##.## 


1.2 


-61.20 




position 


##.### 


1.2 


■B1.20O 






##.### 


-1.2 


-1.200 


+ 


LeacJing or trailing 


+ #.# 


-1.123 


-1.1 




sign 


+ #.# 
#.# + 


1.123 
-1.123 


+ 1.1 
1.1- 






#.# + 


1.123 


1.1 + 


- 


Trailing sign 


#.#- 


-1.123 


1.1- 




if negative 


#.#- 


1.123 


1.H5 


** 


Leading asterisks 


**#M 


23.53 


*23.53 






**iM 


2.53 


**2.53 


$$ 


Floating dollar 


%%#tiM 


123.53 


$123.53 




sign 


$$##.## 


12.53 


H5$12.53 






$$##.## 


1.25 


■H5$1.25 


*•$ 


Leading blanks. 


**$##.## 


123.53 


*$123.53 




floating dollar 


**$##.## 


12.35 


**$12.35 






**$##.## 


1.23 


***$1.23 


tttt 


Exponential format 


#.##tttt 


51235 


0.51 E + 05 




(scientific notation) 


##.##tttt 


51235 


-65.12E+04 


i 


Single character 


I 


"1234" 


1 




of string 


I 


"ABCD" 


A 


% % 


First two characters 
of string 


%% 


"ABCD" 


AB 


%..% 


First two + spaces 
of string 


%-B66% 


"ABCDEFG" 


ABCDE 



for example prints "1". The % field specifier prints either the first 
two left characters of a string, as in 



100 A$="1234" 

200 PRINT USING "%%";A$ 



'string 

'print first two characters 



which prints "12", or two plus the number of spaces between the 
% characters, as in 



100 A$="1234" 

200 PRINT USING "% %",-A$ 



which prints "1234". 

Table 4-1 shows all PRINT USING field specifiers and examples 
of their use. 

When more than one variable is to be printed, then each variable 
of the list uses the same field specifiers. 



1B0 A3i= "##.##" 

200 A=ll. 11 

300 B=2.22 

400 C=.33 

500 D=4.4A 

600 PRINT USINS A«;A,B,C,D 



'using string 
' dummv 
' ancfther 
'and another 
'still another 
'print all four 
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will print "ll.ll«2.22B0.33b4.44". Note that even though a comma 
was specified, the form of the printout used a five-character field 
with no leading or trailing blanks or tabs; four characters were the 
# field specifiers and one was the decimal point. When the string 
field specifiers "%" and "!" are used, then it is possible to construct 
complex formats for printing, such as the code below which takes 
the first two characters of string A$ and priats them, prints a ".", 
and then prints the first three characters of string B$. 

1000 AS="1234" 'first string 

1100 B*="567a" ■second string 

1200 PRINT USINS "■/.■/..•/. -/."SAS.BS 'print PORTIONS OF BOTH 

In this example, the field specifiers were used one at a time in con- 
junction with the variable list to define the printing. A weird oper- 
ation? Yes, but we will never say that such operations will not find 
widespread use for fear of letters from Boise, Idaho, that start out 
"I don't see how you can say that multiple string field specifiers are 
not used often! I use them all the time in my hog breeding program! 
Furthermore, your gross humor is irritating and . . ." 

PRINT USING can be used with double-precision variables to 
provide formatted printing of variables to 14 digits of dollar 
amounts and two cents digits, which should handle receivables 
for most of the current TRS-80 business applications. 

PRINT USING provides a very convenient means to produce 
formatted printing of variables and saves a great deal of special 
coding to accomplish this formatting, as we saw earlier in the 
chapter. Conservative estimates by recent industry experts indi- 
cate about 100,737 lines of code annually saved as a direct result 
of the PRINT USING statement. And there are those who say 
BASIC is not very powerful! 

$4.50 for a Slice of Cheesecake? 

Menus are used not only in posh restaurants, but in posh com- 
puter software. You've seen menus on Radio Shack software, but 
let's illustrate the use of them to jog your memory. Suppose that we 
have written an applications program to process weather data. 
When the program is first loaded, it may display a menu of func- 
tions that may be selected, as shown in Figure 4-6. If entry 4 is 
desired, then the user types a "4", and a new menu of items related 
to "annual weather data" is displayed for further selection. This 
type of implementation is termed "menu-driven." Menus provide an 
easy-to-use format that is very descriptive. This section should defi- 
nitelij be interpreted as a plug for menu use. ( I have a brother-in- 
law in the menu-printing business.) Menu printing is easy, of 
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1 ENTER NEW. WEATHER DATA 

2 MOD I FY WEATHER DATA 

3 CHANGE WEATHER DATA 

4 ANNUAL WEATHER DATA 

5 SAVE WEATHER DATA 

6 LOAD WEATHER DATA 

ENTER SELECTION 





Figure 4-6. Menu use. 




course, and may be implemented by a series of TABs and text, 
followed by a PRINT @ and INKEY$ input as shown below. 



1500 CLS 

1510 PRINT TAB(15) :"1 

1520 PRINT TAB(15) ;»2 

1530 PRINT TAB(15) ;"3 

1540 PRINT TAB(15) :"4 

1550 PRINT TAB<15) ;"5 

1560 PRINT TAB(15) ;"6 

1570 PRINT a 656. "ENTER SELECTION 

1580 A=VAL(INKEY$) 

1590 IF A=0 OR A>6 SOTO 1570 ELSE ON 



ENTER NEy WEATHER DATA" 
MODIFY WEATHER DATA" 
CHANGE WEATHER DATA" 
ANNUAL WEATHER DATA" 
SAVE WEATHER DATA" 
LOAD WEATHER DATA" 



'get value 
A GOTO 200013000,4000,5000,6000,7000 



The code above first clears the screen and then prints the menu 
selections. A TAB is done for each selection to center the selection. 
After the selections are displayed, the prompt message "ENTER 
SELECTION" is displayed at a convenient place beyond the menu 
selections. The input choice is detected by an INKEY$ statement 
which will return a one-character string of the key pressed or a null 
if no keys are pressed. If no keys are pressed or if no numeric key 
is pressed, VAL(INKEY$) will equal 0, and a GOTO back to the 
PRINT @ is made to display the selection message and to look for 
the next input. In some respects, this procedure is very bad. It does 
not inform an inexperienced operator that he has pressed the wrong 
key-it simply ignores it. Oh, I know-what idiot would choose any- 
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thing but the right key? Still, it is always best to attempt to make 
things "idiot proof," to avoid "cuteness," and to be as informative 
as possible for this type of interactive input. (Sad to say, I was once 
jailed for damage to capital equipment when attempting to use a 
program with a bug that ignored my correct input and kept repeat- 
ing "DUMMY! CAN'T YOU READ? NOW ENTER AGAIN AND 
DO IT CORRECT! [sic].") A better response might be 



1500 
1510 
1520 
1530 
1540 
1550 
1560 
1570 
15B0 
1590 
1600 
1610 
1620 
1630 
1640 
1650 
1660 
1670 



CLS 

PRINT TAB(15) 



' cl ear 2-<. 
ENTER NEW WEATHER DATA" 
PRINT TAB(15):"2 MODIFY WEATHER DATA" 
PRINT TAB(15);"3 CHANGE WEATHER DATA" 
"4 ANNUAL WEATHER DATA" 
SAVE WEATHER DATA" 
LOAD WEATHER DATA" 



PRINT TAB(15) 
PRINT TAB(15) ;"5 
PRINT TAB(15):"6 



PRINT a 656. "ENTER SELECTION" 

A3i=INKEYSi 

IF AS="" SOTO 15B0 ELSE A=VAL(A$) 

IF AO0 AND A<7 GOTO 1660 

PRINT a 718. "INCORRECT RESPONSE" 

FOR I=! TO 200 

NEXT X 

PRINT a 718. " 

GOTO 1580 

PRINT "CORRECT RESPONSE" 

END 



get character 
convert if not null 
go -if correct 
notifY user 
delay loop 

OOP 

blank error msg 
^' trv again 
'action for correct inpuT 
'additional code here 



c;' 



More work? Sme, but much more responsive to inexperienced oper- 
ators. (When made into a subroutine, it really does not create a 
great deal of additional work or code, either.) 
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All the Data That's Fit to Print 
(And Some That Isn't) 

If you've made it through the above sermon, you're about to 
be rewarded with some interesting material about line printers. 
Level II BASIC has built-in provisions for printing to line printers, 
of course. 

The two commands that are used to print to a line printer are the 
command LLIST and the statement LPRINT. LLIST is normally 
used to list a BASIC program on the system line printer, while 
LPRINT is used within a BASIC program to print data in much 
the same way as a standard PRINT is used. Operation of the LLIST 
is very straightforward-the format is identical to the LIST com- 
mand for screen display. 

LUST 100-300 

for example, would list program lines 100 to 300 on the system line 
printer. 

LPRINT may be used in similar fashion to PRINT, but you 
should consider the characteristics of the system line printer. The 
number of tab positions on the display is 64, but the number of tab 
positions on some line printers is limited, either physically or under 
software control, to fewer than 64 (20 or 40). In this case, existing 
code that specifies tabs greater than line-printer print positions will 
have to be modified for proper columnization and report printing. 
Conversely, some printers allow more than 64 print positions on a 
line, and you may use the expanded line to include more informa- 
tion on reports. TABs are produced by "padding" text with enough 
spaces to move to the proper tab position. 

One of the differences between PRINT data on the display and 
LPRINTing on the system line printer is that the display is al- 
ways "ready," but the line printer may not be in a ready condition 
due to being out of paper or being "off-line." When this "not ready" 
condition exists, the BASIC interpreter will continuously monitor 
the state of the Hne printer until it becomes ready. The ready state 
of the line printer may be determined by the following code 

100 IF PEEK(14312)<>63 THEN PRINT "NOT READY" ELSE PRINT "READY" 

The code above looks at the hne printer by addressing location 
14312. This system address is not memory, but is the line-printer 
address (37E8 in hexadecimal). The PEEK effectively reads a byte 
of status from the line printer. If the line printer is not connected 
in the system, this status will be 11111111; otherwise, the status bits 
will be as shown in Figure 4-7. Although you could detect each bit 
by ANDing values and comparing the results, it is suflBcient to simply 
make the test above and print out an appropriate error message to 
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2 


1 













1 


1 


1 


1 



a i 4 " 



ALWAYS 1 

■ 1 = FAULT "NORMALLY" 1 

■1 = UNIT SELECT "NORMALLY" 1 
■1 = OUT OF PAPER "NORMALLY" 

■ 1 = BUSY "NORMALLY" 



Figure 4-7. Line-printer status bits. 

the system user. Here again, this error message may be used to in- 
form an inexperienced operator of the line-printer condition. 

Another difference between the display and line printer concerns 
pagination. The display lines scroll oflE the screen as new lines are 
printed, and this is adequate for many applications where hard 
copy is not required. The line printer operates in identical fashion 
to the display except, of course, that all printed hnes are saved on 
the continuous scroll of line-printer paper. If the material covers 
more than one page, it is not conveniently spaced for reproduction 
or for "bursting" the pages for notebooks. The solution to pagina- 
tion is built into Level II BASIC at memory locations 16424 and 
16425. RAM location 16424 holds the number of lines per page, 
while 16425 holds a current line count. The number of lines per 
page is initialized to 67, and the line count is initialized to 0. As 
each line is printed, the line count is increased by 1. If the line count 
equals the number of lines per page, then the line count is reset to 0. 
You can see this by the following code, which displays the line num- 
ber after each line is printed. 

'print line 

'display line number 

'loop back 

On many printers, the number of vertical Hnes per inch is six. 
If the print area is to be 10 inches, we'll have 60 lines per page and 
a margin of three lines (Va inch) on the top and three lines on the 
bottom. The code below is in the form of a subroutine that looks at 
the current line number and skips six lines if the line number is 60, 
to provide a suitable margin for top and bottom. To use the sub- 
routine for printing, set the current line count to before using the 
line printer by 

100 POKE 16425,0 'reset current line count 

At the same time, adjust the Hne printer to "top of form" by posi- 
tioning the paper to three lines down from the top. Every time an 



100 LPRINT "LPTEST" 
200 PRINT PEEK{16425) 
300 GOTO 100 
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LPRINT is performed, call the subroutine so that the "top of form" 
may be implemented at the 60th line. A typical call would be 



1200 LPRINT "VAIUE=";ZZ 
1210 GOSUB lOWX) 
1220 GOTO 1200 

The code follows 



10000 ZZ=PEEK( 16425) 
10010 IF ZZO60 RETURN 
10020 FOR Zl=l TO 6 

10030 LPRINT 

10040 NEXT ZI 
10050 POKE 1642510 
10060 RETURN 



'9et line count 
'return if not time 

r" loop for 6 1 ines. 
'print Une <WITH BLK) 
*~ ' loop 
'clear line count 
'return to calling pro9 



Another difference between the line printer and display is that 
the character sets of each are different. In most cases, the characters 
from ASCII 32 to ASCII 127 are identical, or very similar. This 
range defines special characters, numerics, special characters, upper 
case, special characters, and lower case, ia that order (refer to Ta- 
ble 3-1). The codes 128 through 191 are graphics codes and tab 
codes that 'will probably not be accepted by the hne printer, or will 
cause printing of (somewhat) unpredictable line-printer 'charac- 
ters. The codes from to 31 will vary with the line printer. Some 
line printers have programmable character and hne widths, and 
others have programmable line spacing and things such as the BEL 
code. (The BEL [bell] codes are used on teletypewriters to attract 
the operator's attention for such things as important wire-service 
news stories. ) Here, I will give standard writing ploy number 127- 
refer to your system line printer operating manual for specific in- 
structions. 

We'll be looking at some of the other aspects of using the line 
printer in Chapter 12 ("POKEing Around in Memory") when we 
discuss the video display and line-printer device control blocks 

\ LJk^SjS ) . 
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CHAPTER 5 



Graphic Examples 



We'll be discussing one of the most interesting features of Level 
II BASIC in this chapter, the ability to create displays of graphics 
data. The graphics character set allows us selectively to turn on and 
off 6144 picture elements on the screen of the TRS-80. Graphics 
allows us to create graphs, forms, and animated pictures. There are 
several techniques for using graphics, and we'll be discussing each, 
including a technique of high-speed graphics using strings. 

Back to the Books . . . 

Before we discuss the techniques, however, let's discuss the me- 
chanics of how graphics are implemented on the TRS-80. (Guard, 
stop that reader from sneaking of. . . .) We know from previous 
chapters that there are 1024 print positions on the display screen, 
as shown in Figure 5-1. Each of the 1024 print positions is repre- 
sented by one byte in video-display memory as shown in the figure. 
The electronics in the TRS-80 automatically and continuously cy- 
cles through each of the 1024 video display memory bytes 30 times 
per second. If a byte holds a value of less than 128 (less than 
10000000 in binary), then the logic in the video display electronics 
says, "Aha, I detect a displayable character!" It then converts the 
character code into a displayable character of 5 by 7 dots as shown 
in Figure 5-2 (the top row is always blank). The dots are config- 
ured to represent the ASCII character set shown in Table 3-1. 

However, if the video-display memory byte for any print posi- 
tion of the 1024 is greater than 127, the logic in the video-display 
electronics says, "Another one of those darn graphics characters- 
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XoMB Back! ... fje SAio IMPLEMENT ... J\/oT BjcECute/'' 

troublemakers, every one. Let's see now, how does that scheme 
work again?" The scheme that befuddles the logic also befuddles 
many BASIC programmers. If the code in video-display memory is 
greater than or equal to 128, the first two bits are ignored, as shown 



PRINT 

POSITION 

(15360) 



PRINT 

POSITION 63 

(15423) 



PRINT 
POSITION 

64 
(15424) 



PRINT 

POSITION - 

960 



THESE ARE THE PRINT POSITIONS 
ON THE TRS-80 SCREEN EIEOWO- 
KDJFLSLKDJFJKDEIWOEIURTQPQOI 



EIQOPURJKUFSKDJFIE WITH 1024 



PRINT 

POSITION 

1023 

(16383) 



(XXXXX) = VIDEO DISPLAY MEMORY BYTE 
Figure 5-1. Screen print positions. 
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5 DOTS 

nnnnn always blank 

DBDBD 
■DDDB 

■ nDDH \ 7 DOTS 

■■■■I 
■DDDt 
■DDDB J 



Figure 5-2. Character matrix. 



SIX SEGMENTS OF A 

CHARACTER POSITION 

IN GRAPHICS MODE 



BIT 

r 

(1) 


BIT 
1 
(2) 






BIT 
2 
(4) 


BIT 
3 
(8) 




BIT 
[--- 4 
(16) 


BIT 

5 

(32) 



























1 




1 1 1 1 


, 


r" 


1 1 


1 





1 X X X X X X 



VIDEO DISPLAY 
MEMORY BYTE 



ALWAYS A ONE 
FOR GRAPHICS 



IGNORED 



Figure 5-3. TRS-80 graphics format. 

in Figure 5-3. The next six bits represent the on/ off condition of sis 
segments of the character position, as shown in the figure. 

The logic here is readily understood by the binary code in the 
six bits. The first bit (bit 0) defines the on/ off status of the upper 
left segment, bit 1 defines the upper right, bit 2 defines the middle 
left, bit 3 the middle right, bit 4 the lower left, and bit 5 the lower 
right. The graphics codes for all of the possible combinations from 
128 through 191 are shown in Figure 5-4. To construct any com- 
bination, though, all you have to do is sketch the sis segments, indi- 
cate the on/off condition, and then add the binary weights to 128 
to get the corresponding graphics code for the character, as shown 
in Figure 5-5. The example in the figure produces the code 1284-1 
(upper left) + 8 (middle right) + 16 (lower left) = 153. 
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128 129 130 131 132 133 134 135 



ud Hd ud Di 



136 137 138 139 140 141 142 143 

zumbnbDLumHH 



144 145 146 147 148 149 150 151 




152 153 154 155 156 157 158 159 
160 161 162 163 164 165 166 167 



ty 



168 169 170 171 172 173 174 175 
176 177 178 179 180 181 182 183 
184 185 186 187 188 189 190 191 

asaaiiii 

Figure 5-4. TRS-80 graphics characters. 
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Figure 5-5. Constructing 
combinations of graphics. 



10 110 1 



-128 
+ 16- 
+ 8- 

+_J.- 
153 



GRAPHICS CODE 



SETting Good Examples 

Now that we know the mechanics of the graphics characters, let's 
use the simplest technique of graphics programming to SET some 
good examples. The SET, RESET, and POINT commands allow us 
to selectively set any of the 6144 picture elements. ( Hereafter, we'll 
use the term pixel for picture element, an abbreviation coined from 
the name of an early graphics pioneer. Max von Pixel.) The ar- 
rangement we now have for the 6144 pixels is shown in Figure 5-6. 
There are 128 across (2 per character position) and 48 down (3 per 



PIXEL 
(X=0,Y=0), 

PIXEL 128 
(X=0,Y=1) 



128 PIXELS 



PIXEL 6016 
(X=0,Y=47) 




PIXEL 127 
(X=127,Y=0) 



48 PIXELS 



PIXEL 6143 
(X=127,Y=47) 



Figure 5-6. Display pixels. 
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character position) for a total of 128 X 48 = 6144. Numbering is 
from left to right with a range of through 127, and from top to 
bottom with a range of through 47. The format of the SET, 
RESET, and POINT command is 

SET(x,y) 

RESET(x,y) 

POINT(x,y) 

SET and RESET, of course, set or reset the specified pixel. 
POINT returns the value of the pixel, for off, or 1 for on. Is 
POINT useful? Does the TRS-80 sleep in the woods? {Wait a min- 
ute, how did sleeping in the woods get into the act ... P) Since the 
video display is a memory, it stores the current on/ off status of each 
point. This can be very useful in determining the point status with- 
out referring to another memory location. More on that later. 

One of the more common things that is done to the display is to 
"white it out." The following code whites out the display by two 
nested loops that use the SET statement. Run the program, but 
before you do, get out that old trusty stopwatch you were using in 
your jogging program (you've just got to do something about that 
paunch . . . ) . Record the time it takes to white out the screen and 
save it for comparison with some high-speed techniques we'll be 
using later. 



100 CLS 

110 FOR X=0 TO 127 

120 FOR Y=0 TO 47 

130 SET <X.Y) 

140 NEXT Y 

150 NEXT X 

160 GOTO 160 



'clear screen 
'outer loop 

t' inner 1 oop 
'set point 
'90 dolun columns 
'and then across 
'for nice screen display 



Got it? I have about 49 seconds. (Some of the later techniques will 
cut down on that time by a factor of 100! ) 

Plotting Along With SET/RESET 

The SET/RESET technique of graphics is a slow method for dis- 
playing patterns, but it does lend itself very well to plotting graphs. 
As a matter of fact, it is probably the fastest method for displaying 
graphs of any we'll be discussing. 

If you recall those happy days of high-school algebra, you may 
remember that the "standard" convention for graphs was as shown 
in Figure 5-7. X is along the horizontal axis, and y is along the ver- 
tical axis. X increases toward the right, and y increases toward the 
top. We have a somewhat different situation with the x,y coordi- 
nates for the TRS-80 display. X increases to the right, but the x 
axis is at the top and the y axis increases toward the bottom. Prob- 
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+y 



-X -*- 



■*-+x 



^ ORIGIN 
x = 
y = 



-y 



Figure 5-7. "Standard" graphing. 

lem: How do we teanslate from the standard graph to the TRS-80 
display? Let's plot a simple function to see how we can do this. 

Guns Versus Butter 

Suppose that we take a classic problem of Guns versus Butter. In 
this example, we will attempt to solve the economic problems that 
have been perplexing our country for some time. To make the prob- 
lem more visible, we'll graph it on the ol' TRS-80. 

Guns cost $40 each, while butter costs $4 per pound. If we have 
$200 to spend, we may divide it up between guns and butter. First 
of all, let's define the limits of the graph. If we buy 5 guns, then 
we've used up our $200, and we have pounds of butter. If we buy 
50 pounds of butter, then we can't afford guns. It looks suspiciously, 
then, as though the number of guns ranges from through 5 and 
the number of pounds of butter ranges from through 50. We can 
now set up the layout of the graph we'd like to draw on the video 
display (see Figure 5-8). 




ROOM FOR 
TO 5 GUNS 



=^ 



GUNS 




BUHER 



V 




ROOM FOR 50 POUNDS 
OF BUTTER (GRADE A) 
Figure 5-8. Graph skeleton example. 
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Like most graphing problems of this type, we can divide the work 
into two parts, drawing the skeleton of the graph, and drawing the 
points themselves, or plotting. 

The skeleton of the graph can be drawn by drawing one horizon- 
tal line and one vertical line. The vertical line runs from y=0 
through 47, and we can draw it by 



2BB FOR Y=0 TO 47 
300 SET (0,Y> 
400 NEXT Y 



c: 



setup loop 
draw col umri 
contxnue 



The horizontal line runs from x=0 through 127 on line 47, and 
we can draw it by 



500 FOR X=B TO 127 
600 SET! X, 471 
700 NEXT X 



t' setu 
' drauj 



1 OOP 

roui 
continue 



To complete the skeleton, we need some way of marking the in- 
crements of guns and butter and some labels. We'll use a blank spot 
evei-y 2 points for butter, and a blank spot every 9 points for guns. 
(We chose these increments because the maximum value of 50 
pounds of butter would be at x=100 and the maximum value of 5 
guns would be at y=45; neither value would cause illegitimate x 
or y values.) 

The following code would clear the tick marks and label each 
of the axes. 



800 FOR X=2 TO 100 STEP 2 

900 RESET (X,47) 

1000 NEXT X 

1100 FOR Y=47 TO 2 STEP -9 

1200 RESET (0,Y) 

1300 NEXT Y 

1400 PRINT a 5,"6UNS": 

1500 PRINT a 936, "BUTTER" ; 



C- setup tick loop 
'blank tick mark 
' cont 1 nue 
n'setup tick loop 
I 'blank tick mark 
' continue 
'vertical title 
' horizontal title 



The skeleton we have now looks like Figure 5-9. All we need to do 
at this point to solve the world's economic problems is to do some 
meaningful plotting. The problem resolves into 

# GUNS ' $40 -(- # LBS BUTTER * $4 = $200 

One way of implementing this problem is to step the number of 
guns from through 5, since we know that this is the range of the 
number of guns. The code below does this and computes lie num- 
ber of pounds of butter for each quantity of guns. 



1600 FOR S=0 TO 5 
1700 B=(20B-G«40)/4 
1B00 NEXT 5 



■'setup computation 

'compute butter 
■ ' continue 
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GUNS 



Figure 5-9. Partial skeleton. 



BUHER 



The only remaining thing to do is to plot the points for each set 
of guns and butter. The horizontal distance or displacement for the 
X value defining the number of pounds of butter is found by taking 
B, the number of pounds of butter, and multiplying it by 2 (there 
are two increments for every pound of butter). The vertical dis- 
tance for the y value defining the number of guns is found by mul- 
tiplying G, the number of guns, by 9 (there are 9 increments for 
every gun). Putting this calculation in the above code produces 



1600 FOR 5=0 TO 5 

1 700 B= < 200-5*40 ) /A 

1720 X=B»2 

1740 Y=47-G«9 

1760 SET (X,Y) 

1B0B NEXT 5 



-'setup computation 
' compute butter 
'x displacement 
'y displacement 
' set point 
' continue 



With the addition of a screen clear at the beginning, the com- 
pleted program looks like this 



100 CLS 

200 FOR Y=0 TO 47 

300 SET (0,Y) 

'tB0 NEXT Y 

500 FOR X=0 TO 127 

600 SET (X, 47) 

700 NEXT X 

800 FOR X=2 TO 100 STEP 2 

900 RESET (X>47) 

1000 NEXT X 

1100 FOR Y=47 TO 2 STEP - 

1200 RESET !0.Y) 

1300 NEXT Y 

1400 PRINT a 5^ "GUNS" ! 

1500 PRINT S 736, "BUTTER" 

1600 FOR 3=0 TO 5 

1700 e=(200-S«40)/4 

1720 X=B»2 

1740 Y=47-G*7 

1760 SET (X,Y) 

1800 NEXT 5 

1900 GOTO 1900 



V. 
[ 



ar scrt-en 

setup i o o p 

drauj col umn 

continue 

s-etuF 1 OOP 

drauj t-oiu 

cont 1 nue 

setup tick 1 OOP 

blank tick ma r k 

continue 
' setup tick 1 OOP 
' bl ank tick mark 
' continue 
rtical title 
r- 1 z o n t a 1 title 
' setup computation 
■" compute butter 
' X di^-p I acement 
' r di spI acement 
' set pomt 
' continue 
OP here for displ av 



The most important point (no pun intended) in the above pro- 
gram is that the usual graphic y value must be converted to the 
screen graph y system by subtraction from 47. This must always 
be done for a graph with y coordinate at the bottom of the display. 

11740 Y=47— G*9 'y displacement 
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The Guns and Butter graph illustrates the general approach that 
you should take in graphing a particular function, or set of points 
that define a graphical relationship. 

1. Determine the appropriate ranges of both the x and y vari- 
ables. 

2. Draw the skeleton of the graph and mark off the horizontal 
and vertical axes with appropriate tick marks to cover the 
range. Numeric values, of course, may be put on or near the 
axes. 

3. Compute the function and get x,y values. 

4. Convert the x,y values to the TRS-80 video coordinates by us- 
ing the same x value, but by finding a new y value by subtract- 
ing the old value from 47. 

5. Plot the point by a SET. 

6. Repeat for all points. 

In the above example, we used values for x and y that were some- 
what contrived. X and y turned out to be integer values only; that 
is, none of the x and y values were mixed numbers containing inte- 
gers and fractions. What happens if we do use mixed numbers for 
X and y? If we attempt to set, say, x=12.7 and y=13.5, the x,y values 
are truncated to x=12 and y=13. This means that x and y can be 
computed without worrying about invalid values, unless x is less 
than 0, X is greater than or equal to 128, or y is greater than or equal 
to 48. 



A Moving Experience 

The SET and RESET commands can be used together to give 
the illusion of motion for dots, lines, starships, flying rolling pins, 
and other items. Let's take the simplest case first, a moving dot. 
To make a dot appear to move, the dot must be SET in one posi- 
tion, RESET in that position, and then SET in the next position. 
The timing should be such that the motion appears fluid (see Fig- 
ure 5-10). 

The simplest code for this is shown below. The speed of the 
single dot moving across line 24 is about 1% seconds per crossing. 



H 








■ 




r 1 
1 1 














*-ivluTION 


SET 




RESET 
Figure 5-10. S 


im 


SET 
pie animation. 




RESET 
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This is about the maximum speed for a SET/RESET approach. 
The dot can be slowed down by inserting "time wasters" at state- 
ment 350. Try various "time wasters" such as 350 REM or 350 A=0 
or 350 A=l''2 to see how they affect the speed of the dot. 



100 CLS clear screen 



200 FOR X=0 TO 127 
30B SET (X,24) 
4B0 RESET (X,24) 
500 NEXT X 



'animation loop 
' turn dot on 
'turn dot off 
■ continue 



The same principle of animation may be applied to more complex 
figures. The more complex the figures, of coiurse, the more difficult 
it is to know which dots to turn on and off. We'll show some more 
examples of animation later in this chapter when we discuss some of 
the faster graphics methods. 

Good Points to Consider 

What the heck is the purpose of the POINT command? Beats me 
—let's go on to the next subject. . . . 

But seriously, folks ... the POINT command is a way of check- 
ing each of the 6144 pixels on the video display to see whether they 
are turned on or off. But don't we know at all times whether or not 
the pixels are on or off? Not necessarily. We could keep track of all 
pixels that are on in a long table, and then search that table to find 
out the state of the pixel in question. But why not use the POINT 
command to check the pixel without spending a lot of time search- 
ing through a table of values? After all, each pixel is really a one- 
bit (0 or 1) memoiy in itself. The POINT command makes it pos- 
sible to check the state of any one of the 6144 bits that represent the 
pixels on the screen. 

There are times when it's very convenient to use the POINT 
command in place of keeping a long list of turned-on pixels. Sup- 
pose that we have turned on points at random and now wish to 
check whether a pixel is on. The code below shows a simple exam- 
ple of the approach. It searches the video memory by a POINT 
command to find the one pixel that has been turned on by a random 
selection. The random selection was made by the RND command, 
which we'll talk about a little later on. 

1000 CLS 'clear screen 

1100 X=RND(127) 'find random x 1 to 127 

1200 Y=RND(47) 'find random y 1 to 47 

1300 SET <X»Y) 'turn on point 

1400 FOR X=0 TO 127 

1500 FOR Y=0 TO 47 

1600 IF P0INT(X.Y)=-1 PRINT X^Y 

1700 NEXT Y 

1 800 NEXT X 



-'setup outer loop 

setup inner 1 oop 
t on 
ch 
continue ujith outer 



L' setup inner 1 o 
'print If point 
'continue searc 
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Notice that a -1 was returned for the POINT in only one case, 
the case in which the pixel was found to be ON. All other pixels 
caused the POINT to return a zero, indicating that they were OFF. 

The POKE Graphics Method 

The second approach to graphics that can be used is the POKE 
method. We know that video-display memory is exactly that, a set 
of 1024 memory locations. The addresses of the 1024 locations range 
from 15360 to 16383. This area is in the first 16K (16 X 1024) loca- 
tions of the TRS-80 memory address range. The video-display mem- 
ory shares this memory along with Level II BASIC and some dedi- 
cated addresses for the line printer and other devices (see Fig- 
ure 5-11). * 

LOCATION 





BASIC 

INTERPRETER 

IN ROM 



12287 
12288 



15359 
15360 

16383 
16384 



DEDICATED 

ADDRESSES 

(LINE PRINTER, ETC.] 



1024 LOCATIONS 

VIDEO DISPLAY 

MEMORY 



FIRST 16K (16384) 
LOCATIONS IN MEMORY 



START OF 
RAM 



Figure 5-11. Video-display addresses. 



To address any of the 1024 print positions, all that we must do 
is find the displacement of the print position from the start of video- 
display memory as shown in Figure 5-12. Since there are 64 char- 



89 



LOCATION 




DEDICATED 
ADDRESSES 






(START) 15360 — 
15424 - 
15488- 


— 


VIDEO 
DISPLAY 
MEMORY 






16320 — 


— 








(L1NE15,CP0) 




START OF 
RAM 







15423 (LINE 0, CHARACTER 
15487^ POSITION 63) 

(LINE 1, CP 63) 



16383 (LINE 15, CP 63) 



Figiu-e 5-12. Finding the print-position displacement. 

acters per line and 16 lines per display, the video-display memory 
address for any character position is 15360 + (line number *64) + 
(character position in line). To address line 8, character position 
10, for example, we find 

15360 H- 64 ' 8 + 10 = 15882 

Here, we were using as the first line number and first character 
position on the line. Referring to our ASCII codes of Table 3-1, 
we can store a "1" on that character position on the screen by 



100 CIS 


'for set 


200 POKE 15882,49 


'set pixel 


300 GOTO 300 


'loop here 



The POKE method is very useful when we must fill the same 
graphics character across an entire line or portion of a line. Did you 
save the timing of the SET/RESET "white-out"? Let's compare it 
with one using the POKE method. The following code whites out 
the display by POKEing a 191 (10111111) into each of the 1024 
character positions of the video display. The value 191 represents 
all ones for the six pixels and a one bit to signify graphics. For the 
fastest speed, don't enter the comments! 



10 CLS 

20 FOR X=I5360 TO 163B3 

30 POKE X, 191 

40 NEXT X 

50 SOTO 50 



'clear- screen 
r 'screen memorv limits 

'all 6 Pixel s on 

' continue 
'looks nice 
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Seven and a half seconds! Quite a difference between the POKE 
and SET /RESET methods! 

Of course, any of the 64 patterns shown in Figure 5-4 may be 
output as a line or portion of a line using the POKE technique. 
The following code draws a stop light using the POKE method. 
When the areas involved are small, the method is fast enough that 
you can at least think about animation techniques. 



90 DATA 191,131,131,191,171,131,131 


191 








92 DATA 191,131,131,191,131,171,151 


131 


94 DATA 128,170,149,128 




1B0 


CLS 


'clear screen 


iia 


FOR 1=0 TO 4 




-'setup row loop 


120 


FOR J=0 TO 3 






-'setup column loop 


130 


READ A 






'get graphics value 


140 


POKE lS360+330+J+I*64,A 






'poke into roui, column 


150 


NEXT J 






go for next column 


160 


NEXT I 




'go for next row 


170 


FOR 1=0 TO 2 




p 


-'setup light output 
•flash Ught 


1B0 


POKE 15360+351+1*64,167 






190 


POKE 15360+332+1*64,167 






'in tiuo positions 


195 


IF 1=1 THEN K=300 ELSE K=1000 






'use short value for Ye i 


200 


FOR J=0 TO K 






p ' timing 1 OOP 
^'for light 


210 


NEXT J 






220 


POKE 15360+331+1*64,131 






'now turn off light 


230 


POKE 15360+352+1*64,131 






' in two positions 


240 


NEXT I 






' continue 


230 


GOTO 170 




^' 1 


OOF 


for next CYCle 



How about addressing the 6144 pixels randomly using the POKE 
technique? I was afraid you'd ask. . . . While it's easy to compute 
the address of a character position for the POKE, it's rather difficult 
to compute the address of a pixel. Furthermore, computing the 
pixel address and performing a POKE for the pixel bit actually 
takes longer than the equivalent SET/RESET. For those masoch- 
istic programmers out there who wish to try it anyway. . . . 

To find the POKE address for a given x,y, perform the follow- 
ing steps. 

1. Divide x by 2 and save the quotient as XQ. XQ=INT(X/2) 

2. Save the remainder as XR. XR=X-(XQ'2) 

3. Divide y by 3 and save the quotient as YQ. YQ=INT(Y/3) 

4. Save the remainder as YR. YR=Y-(YQ''3) 

5. The POKE address is given by A=15360-1-YQ'64-FXQ. 

To SET a bit using POKE, 

1. Get the value at the POKE address by B=PEEK(A). 

2. Or in a bit value as follows: B=:B OR 2t(YR'2H-XR). 

3. Make certain the most significant bit is set by ORing in 128. 
B=B OR 128 

4. POKE the value back in the address. POKE A,B 
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To RESET a bit using POKE, change the value in step 2 to 
255-2t(YR''2+XR) and and instead of ORing. 

B=B AND (255-2t(YR»2+XR)) 

String Graphics and the Chattanooga TRS-80 

Do you still have that stop watch available? Execute the follow- 
ing program to "white-out" the screen, and time its duration. 



100 CLEAR 500 

200 CLS 

300 A»=STRIN6S<6A,CHRJ(191 1 1 

400 FOR 1=1 TO 16 

500 PRINT A*! 

600 NEXT I 

700 SOTO 700 



"clear string s-pace 

'clear screen 

'get graphics string 

p ' setup 1 OOP 

j 'print line 

"- ' loop 

'for displ av 



This time the screen white-out took less than a second! Obvi- 
ously, this method is the fastest of any so far— 75 times as fast as 
the SET/ RESET method and 10 times faster than the POKE imple- 
mentation. This method uses one of several methods to establish a 
string variable. Once the string has been established, it can be 
PRINTed very rapidly because it requii-es no computation; the 
string values are just simply printed as they appear! 

To see another example of this method, let's estabUsh a display 
other than a continuous string of the same pattern. We'll use an 
old-time locomotive as the pattern we want, as shown in Figure 5- 
13. The choo-choo is made up of 36 character positions with 6 pixels 
in each character position, as shown in the figure. 
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Figure 5-13. Choo-choo pattern. 
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We must take each of the 36 character positions and translate 
them into a proper graphics code by referring to Figure 5-4. When 
we do this, the codes are 

TOP ROW 188,188,140,140,172,128,128,128,139,191,135,128 
MIDDLE ROW 186,191,188,188,190,191,191,191,191,191,191,157 
BOTTOM ROW 130,139,191,191,135,131,131,139,191,191,135,129 

Just to be certain that we have the proper codes, let's draw the 
figure in the center of the screen. We'll use three strings, one for 
each row in the figure. 

100 CLEAR 1000 .<.,,3,. ,,.r.j|.,g .^^^^ 

2™ CLS -clear srreen 

?SS i!°^™*"^^'-'=™*"i5S)-HCHRS< 140)+CHRS( 1«0)+CHRS( 172)+CHRS( 12B)+CHRS( 12S)+CHR$( r 

fSS ?*='^™*"'S'''*™f*""l'+=™*<iaB'+<:HR»(188)+CHRS<190)+CHRS(191)+CHRt(191)+CHR*(l 

auttj r-rtiH I m djhi a* t ' f>r 1 n i" f i r=-- 1 rr.ui 

700 PRINT a 602,B$; .p,.„,t se<:;„d rcu, 

800 PRINT a 666, «: .print third r-OM 

900 GOTO 900 .,„„p f,^,.^ ,,,„, <,ij„|^,. 

To make the choo-choo move, we'll move it a character position 
at a time. If we add leading blanks to the strings, we will get an 
automatic erase of the old image. With the addition of some smoke, 
vi'e've completed the animation 

840 IF RND(3) = 1 GOTO 850 ELSE PRINT @ l-54,"0"; 



100 CLEAR 1000 
200 CLS 
300 AS^ 



string space 
screen 



300 AS=" "+CHR*(ia8)+CHR«<188)+CHR$<l'i0)+CHR«(li,0) + CHR3.(172) + CHRt(12B)+CHR«(12a)+CHf 
400 BJ=- ■+CHR$(186;+CHR»(191)+CHR*<ia8)+CHRS(lBB)+CHRS(190)+CHRS(191)+CHR«(1911+CHf 
m Sr/^?"''^'-'2'"*'="''*'""*'=™*"""'*™''*<"»'*™R*"35)+CHR«(!31J+CHRS(131)+CHf 



6BB FOR 1=512 TO 563 
650 PRINT a I, AS! 
700 PRINT a 1+64, BS! 
B0B PRINT a 1+128, CJ! 
825 FOR J=l TO 20 
830 NEXT J 



setup loop for movement 
'print first rouj 
'print second row 
'print third roiu 

r'delav for effect 

'-' loop 



840 IF RND<31=1 SOTO B50 ELSE PRINT 3 1-54, "0"! 

lit I^^XT I I ,„,„^^ t„ the right 

900 SOTO 900 <-,|„„p ^^r^ ^^^ displav 

Note that in the above code, we used a timiiig loop (FOR J=l 
TO 20: NEXT J) to actually slow down the animation! We're mak- 
ing progress in speeding up our graphics! Another trick we could 
have used would be to add cursor characters in the string so that A$, 
B$, and C$ would be concatenated into one super string. Adding 
STRING$ (13,CHR$(24)) and CHR$(26) would move the cur- 
sor left 13 positions and down one position, in preparation for the 
next row. You might like to work that out on your own (reviewing 
cursor positioning in Chapter 3 will help refresh your memory about 
cursor movement). 
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String Graphics Using Dummy Strings 

There is an additional technique that we can use to implement 
string graphics, the technique of "dummy strings." For this method, 
we use a dummy string equal in length to the desired string and then 
fill in the graphics characters required. When a number of strings 
are used for graphics, this technique saves on string initiahzation 
and string storage requirements, and is easier to use. We'll see how 
this works using one large string with cursor control movements. 

1000 CLB 'clear screen' 

1100 A$="THIS IS A DUMMY STRING TO BE FILLED WITH GRAPHICS AND CURSOR CHARS!" 

1200 DATA 128.1B8.1BB>140. 140, 172> 128. 128, 128, 139. 191.135,128 

1250 DATA 26,24,24,24,24,24,24,24,24,24,24,24,24.24 

1300 DATA 128.186.191.188.188.190,191.191,191,191,191.171,157 

1350 DATA 26.24.24.24,24,24,24,24.24.24.24,24,24.24 

1400 DATA 128.130.139.191,191,135.131.131,139.191,191.135.129 

1500 B=VARPTR<A!E) 

1600 C=PEEK(B+2)*256+PEEK(B+l ) 'find actual addres 



1700 FOR I=C TO C+66 
1800 READ A 
1900 POKE l.A 
2000 NEXT I 



'setup loop to fill string 
'get one bvte value 
'poke into string 

' 1 OOP 



r- -del. 
>- 'loo 



int one lone string 
delay for effect 



2100 FOR 1=512 TO 560 p 'setup loop to move 

2200 PRINT a l.A*: 

2300 FOR J=l TO 30 

2400 NEXT J 

2450 IF RND(3)=1 GOTO 2500 ELSE PRINT 3 1-54. "B" ! 

2500 NEXT I "-'move to right 

2600 GOTO 2600 'to retain display 



Unlike the other string graphics mode, no CLEAR is necessary, 
since the BASIC interpreter will use the string text in the A$ state- 
ment for PRINTing the string. The dummy string is estabhshed by 
using any text string that is equal to the number of graphics char- 
acters to be printed. Next, the graphics characters themselves are 
constructed using a DATA statement. The first two rows have the 
cursor control characters 26 (down cursor) and 24 (left cursor) ap- 
pended to move the cursor back to the beginning of the next row. 

We know from Chapter 3 that the VARPTR function will find the 
address of the string variable parameters for A$ in the following 
order: 

(B) =:A$ length 

( B-fl ) = Least significant byte of A$ address 

(B-l-2) — Most significant byte of A$ address 
C is computed to contain the address of A$. This address, unHke a 
string that has been constructed from CHR$ or concatenation, is the 
address of the string within the A$ statement itself. The READ loop 
reads each of the DATA values and puts them into the dummy 
string. Now we have a string for A$ made up of the actual graphics 
characters we require. This is used in the PRINT© statement in the 
same fashion as the other string graphics mode, except that we now 
have one large string. 
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The speed of this graphics method is about the same or slightly 
faster than the previous string method, once the dummy string has 
been filled with the proper characters. The program below "whites 
out" the screen using this method. 

3000 A3i=" -fcz, spaces here' 

3100 B=VARPTR(A*) 'get string block locn 

3200 A=PEEK(B+2)»256+PEEK<B+l) 'Set address of 'tring 

3300 FOR I=A TO A+63 r- ' set fill loop 

3400 POKE 1,191 .fill uith all on chrs 

3500 NEXT I L- loop 

360B CLS "clear screen 

3700 FOR 1 = 1 TO 16 i-'sc-tup loop for lines 

3800 PRINT A»! 'fill line 

3900 NEXT I ^'loop 

4000 GOTO 4000 'loop for appearance 

One important point about this method: Do not attempt to edit the 
lines after they have been initialized! 

Graphics Review 

We've discussed four graphics methods: the SET/RESET method, 
the POKE method, the string method, and the dummy string method. 

Let's just recap how to apply these methods: Use SET/ RESET for 
plotting graphs and random data. This method is useful any time 
points must be displayed that are not in the same area, or that do 
not have a similar pattern. The POKE method is used as a simple, 
direct way to draw horizontal or vertical line segments that have 
an identical pattern or for drawing blocks of patterns (and it's much 
faster than the SET/RESET method). The string methods are used 
when animation is to be performed. They're extremely fast but re- 
quire a great deal of work in translating the graphics patterns to 
be output into corresponding data values. The dummy string method 
is perhaps the easiest for setting up a large number of graphics data, 
but it does require a means to move the data into the dummy string. 

Is there a faster graphics method? Yes, there is a method that is 
even a hundred times faster than the string method. The kicker is 
that this method uses machine language. We'll be describing some 
of the interfacing techniques to machine-language subroutines in a 
later chapter, but we cannot cover the subject in less than another 
book! Take a look at our TRS-80 Assembly-Language Programming 
(62-2006) if you're interested in learning how to create machine- 
language programs. 

How to Draw a Straight Line 

Drawing a straight line on the video display is not always easy 
to do. The TRS-80 video screen is divided into 128 by 48 picture ele- 
ments, as we have seen. Now, the more pixels that there are on a 
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display, the finer the resolution of the display, and the straighter the 
lines liat can be drawn. Compare the line drawn on a portion of a 
screen that has 100 pixels (10 by 10) with one that has 400 (20 by 
20) (see Figure 5-14). 



10 



10 







_ _, 'J 








L „ 






Figure 5-14. Drawing straight lines. 

In attempting to draw a straight Une between two points, a cer- 
tain amount of "jaggedness" has crept in. This jaggedness is unavoid- 
able, and the 6144 pixels on the TRS-80 represent a good compro- 
mise between a reasonable resolution and a manageable number of 
points. (Remember, each point takes a discrete amount of time to 
process, and painting a white screen with 128 by 128 pixels would 
take about 2% times as long as 6144 pixels. ) 

How can we draw a reasonably straight line between two points? 
One way this could be done, of course, would be to work with the 
equation of a straight line for a graph. Everyone knows that this is 
Y=MX''C. Or is it Y=MX/C . . . ? Or, wait a minute . . . I've got it 
here in my notes. . . . 

On second thought, let's look at a way that is just as efficient 
(probably more so) and that takes very little math and no analytic 
geometry. Suppose that we have two points that must be connected 
by a straight line. We've shovra the number of points between the 
two points in Figure 5-15. 

The following code draws a straight line between the two points 
by determining the minimum nmnber of points to iill every pixel 
between the two points. The code tries to minimize SETting the 
same pixel ON more than once, since this is an obvious waste of 
time. On the other hand, it makes certain that every pixel of the 
jagged line between the two points is SET that must be SET. Of 
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X2-X1 IN THE X OR HORIZONTAL DIRECTION 
Y2-YI IN THE y OR VERTICAL DIRECTION 



X2-X1 



Y2-Y1 



THESE PIXELS MUST BE FILLED 




X2,Y2 



Figure 5-15. Connecting two points. 

course the code is a subroutine and must be called using something 
such as: 



100 INPUT XT, Yl, X2, Y2 
110 GOSUB 10000 
120 GOTO 100 



u 



2 points 

'call line subroutine 
loop 



10000 IF ABS(X2-X1)<ABS(Y2-Yi) 

10005 DY=(Y2-Y1)/ABS(X2-X1) 

10010 IF X2>X1 GOTO 10070 

10020 FOR I=X1 TO X2 STEP -1 

10030 SET (I>Y1) 

10B40 Y1=Y1+DY 

10045 IF YK0 THEN Y1=0 

10050 NEXT I 

10060 RETURN 

10070 FOR I=X1 TO X2 

10080 SET (I,Y1) 

10090 Y1=Y1+DY 

1B095 IF YK0 THEN Y1=0 

101 00 NEXT I 

10110 RETURN 

10200 DX=!X2-X1)/'ABS(Y2-Y1) 

10205 IF Y2>Y1 GOTO 10300 

10210 FOR I=Y1 TO Y2 STEP -1 

10220 SET (Xl> I) 

10230 X1=X1+DX 

10235 IF XK0 THEN X1=0 

10240 NEXT I 

10250 RETURN 

10300 FOR I=Y1 TO Y2 

10310 SET (Xl.I) 

10320 X1=X1+DX 

10325 IF XK0 THEN X1=0 

10330 NEXT I 

10340 RETURN 



GOTO 10200 

'get delta y 
'90 if >:2 TO RIGHT 
'x2 to left 
'set point 
'add delta y 
' maY happen once 
"" 'continue loop 
return to calling prog 
'x2 to right 
'set point 
'add delta r 
'maY happen once 
'continue loop 
'return to calling prog 
'find delta x 
'go If y2 below 
' y2 above 
set point 
add delta x 
j 'maY happen once 

' continue 1 oop 
return to cal 1 ing prog 
' y2 above 
'set point 
'add delta x 
'maY happen once 
'continue loop 
' return 



r;: 



97 



The code above functions as follows: It compares the distance in 
the y direction with the distance in the x direction. If the x distance 
is greater, then the code will step x in increments of 1 from XI to 
X2. For each x step, a "delta" value of y is added to the current Yl 
value. The DY value is derived from the y distance divided by the 
number of steps in x. If the x distance is less than the y distance, 
then the code will step y in increments of 1 from Yl to Y2 and vary 
XI by adding a delta x. In the process of adding DX or DY, it is 
possible to go over Yl=47 or Xl=127. However, as we saw earlier, 
an X or y value that is fractionally over is truncated. Given sufficient 
precision, XI and Yl will never be equal to or greater than 128 or 
48, respectively. 

A different situation exists when the value of XI or Yl decreases. 
Because the delta is fractional, XI or Yl may become very small 
negative numbers. Because of this, a check is made for negative XI 
or Yl, and the variable is set to if a negative value has been com- 
puted. The negative value will only occur on the last point to be 
SET and only on the extreme top (Y) or left (X). 

A test driver for the subroutine in the code below will allow you 
to input XI, Yl, X2, Y2 values to exercise the subroutine. 

The subroutine may be used as the lines are required, or it may 
be used to draw an initial pattern by setting up values in a DATA 
statement or array and by READing the values with a call to the 
subroutine for each set of four as shown below. A convenient way 
to detect the end of the data is by an illegal set of points such as 
-1, -1. 



100 DATA 201 201 30 


20 


200 DATA 30120,30 


30 


300 DATA 301 301 20 


30 


400 DATA 201 30, 20 


20 


500 DATA 201 201 30 


30 


600 DATA 201 30 1 30 


20 


700 DATA -1,-1,-1 


-1 


750 CLS 




B00 READ Xl,YliX2 


Y2 


900 IF Xl=-1 GOTO 


900 


1000 GOSUB 10000 




1100 GOTO B00 





c 1 ear scr-een 
"'read tuio point definitions 
'loop for aesthetics 
■■ drauj that 1 ine 
**-' 1 OOP for- next 1 ine 
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CHAPTER 6 



Tables, Chessboards, and the 
Fourth Dimension 



In this chapter and the next, we'll be talking about how to orga- 
nize data. In the jargon of computer science, organization of data 
is treated under the name data structures. The three data structures 
we'll discuss in this chapter are lists, tables, and arrays. In the next 
chapter, we'll talk about how to maintain the order of tables and 
arrays, and about a third type of data structure called a linked list. 
We'll limit our discussion to those data structures used commonly 
in BASIC programs and forget about such esoteric structures as the 
Flying Buttress Array, the Catenary String, and the Starboard List, 
all of which cause computer science students many sleepless mid- 
term nights. 

The simplest form of a data structure is a list of items. A list rep- 
resents a set of data that is probably related in some fashion. An ex- 
ample might be a shopping list for the grocery store: 

1 lb butter 

1 qt milk 

3 sm tomatoes 

1 can orange juice 

1 qt oil 

1 can peas 

All the items are related except one. Which one? Exactly— the 3 sm 
tomatoes are the only items that are not packaged! This only points 
to the fact that lists can include any number of related or non-related 
items at the user's discretion. 
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BASIC DATA Lists 

We have a built-in provision in Level II BASIC for creating a list. 
The DATA statement allovs^s us to build a Hst as long as the memory 
we have available. The DATA statements belovs' build our list. 



10 


DATA 


"1 


LB. BUTTER" 


17 


DATA 


"1 


QT MILK" 


14 


DATA 


"3 


BH TOMATOES" 


16 


DATA 


"1 


CAN ORANGE JUICE 


18 


DATA 


"1 


ST OIL" 


20 


DATA 


"1 


CAN PEAS" 



We can read the list by performing a READ command. The code 
shown below continuously READs the list we established in state- 
ments 10-20 until it runs out of data. At that point, the BASIC inter- 
preter, having looked throughout the current BASIC program un- 
successfully for more DATA statements, prints the message "OD 
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Figure 6-1. Example of DATA list. 



ITEMl 


"1 LB BUTTER" 


2 


5 


3 


3.7 


4 


"1 QT OIL" 


5 


377258 


6 


.005 


7 


2 



ERROR IN 1000". In the case of this list, each string (such as "1 LB 
BUTTER") was one item in the list. Every time a READ was per- 
formed, the next item from the list was read. 



1000 READ A$ 
1010 GOTO 100O 

We can have any number of items in the DATA list as long as we 
either have a data statement for each one or separate the items by 
commas. The types of items in the list can also be mixed— we can 
intersperse strings with numeric data of several types. BASIC auto- 
matically makes each entry a separate item. The statements 

100 DATA "1 LB BUTrER",5,3.7,"l QT OIL" 
110 DATA 377258,.005,2 

would create a list of 7 items arranged as shown in Figure 6-1. 
Every time a READ was performed, the next item in the list would 
be read. Of course, we could not have tried reading a string with a 
"100 READ A". If we had, an error would have resulted. 

We mentioned earlier that the list could be as long as the mem- 
ory available. When using DATA statements, there is only one list. 
And that list includes every DATA statement in the current program, 
the same way that the Lord High Executioner's list in the Mikado 
included all of his enemies. 

DATA "PEOPLE WHO HAVE FLABBY HANDS AND IRRITATING LAUGHS" 
DATA "PERSONS WHO IN SHAKING HANDS WITH YOU SHAKE HANDS 

WITH YOU LIKE THAT" 
DATA "THE BANJO SERENADER AND THE OTHERS OF HIS RACE" 

When we have three DATA statements in a 2000 statement pro- 
gram, one at the beginning, one at the middle, and one at the end, 
such as 

100 DATA 0,1,1,2,3,5,8 



1200 DATA 13,21,34,55 

2O00 DATA 89,144,233 

101 



IBB CLS 'clear- screen 

110 PRINT "height vs weight" 'print title 

120 INPUT "input height in inches'UH 'input height 

130 IF IH<5a OR !H>72 GOTO 120 'trr again if off scale 

140 RESTORE 'reset pointer 

150 READ HT.WT 'read ht.iut rrcm lis-t 

160 IF HT=IH PRINT 'FOR HEIGHT OF" ;HT :" WEIGHT SHOULD BE";WT ELSE GOTO 150 

170 GOTO 120 'go for- next ht 

1B0 DATA 50. 65, 51^67, 52i75, 53, SB, S5!95!5fe. 101i57. 106158! Ill 

19B DATA S"?, 120,60,125,61, 131,62, 136,63, 144,64, 148,65, 156,66, 161 

200 DATA 67, 167,68, 172,69, 180,70, 164,71,253,72, 197 

Figure 6-2. DATA list program. 

then we've created a fourteen-element list of items. The data state- 
ments can be put anywhere; the BASIC interpreter will skip over 
them in the normal flow of execution and simply note where they 
are and that they constitute the one and only data list. 

READS and RESTORES 

Every time a READ is executed, another item in the data list is 
read, and an imaginary pointer is adjusted to point to the next 
DATA item. Actually, the pointer is not so imaginary. There is a 
pointer used in the BASIC interpreter, but it is not accessible to 
John Q. Programmer, except via the RESTORE statement. The 
RESTORE resets the pointer to the beginning of the DATA list. 
Any time we want to start at the beginning of the DATA Mst, we 
can take advantage of the RESTORE. 

A good example is shown in Figure 6-2, where we have a program 
to access the DATA list to find the average weight for a given height. 
In this case, the data is arranged in groups of two, height (in inches) 
followed by average weight (in pounds). Every READ reads two 
items, height into HT and weight into WT. When the height matches 
a given input height, then the weight is printed. A RESTORE then 
resets the pointer in preparation for the next input. Note that a mul- 
tiple READ has been done with two variables. We can read as many 
variables as we can pack into each READ statement. 

Mixing It Up 

Having one huge DATA list of mixed variables is a mixed blessing. 
It's a convenient way to establish a long list of constant data, but it 
does not allow an easy way to set up independent data lists. If we 
read three different sets of data, as in this example, 

100 REM LIST OF TELEPHONE NUMBERS 

110 DATA "555-1212", "999-800B", "999-1234' 

i 

1200 REM LIST OF DISTANCES IN MILES 
1210 DATA 1.2,3.6,3.7,9.2,11.8 



183B REM LIST OF LISTS 

1040 DATA "STARBOARD", "PORT", "BOTTOMS UP" 



102 



then we wind up with one integrated hst of 11 items. How do we 
locate each group conveniently? We could be aware of the number 
of items in each group. That way, to get to the third group, the list 
of lists, we could execute 



20B0 RESTORE 






' reset 


2100 FOR 1=0 TO 2 






~' j.e 


2200 READ A* 






' re. 


2300 NEXT 






-Mo 


2400 FOR 1=0 TO 4 






r"' -■- 


2500 READ A 






' re. 


2600 NEXT 






-Mo 


2700 REM WHEy! FINALLY 


MADE 


IT' 





o 1 n t e r- 
setup for first g r o i.n= 
ad and thrMju auia.- 



tup for :^'rid group 
ad and throw atsiav 



This code bypasses the first two groups by READing and discarding 
DATA items. Two separate READs must be made because the first 
group is a string Hst while the second group is a numeric list. 

Another way to find the proper group is to insert a unique code at 
the beginning of each group and then search for that code to set the 
pointer to the proper data. This technique is shown in Figure 6-3, 

1000 DATA -1 

1010 DATA 23.5,6,78. 115,5. 4i6, 89, 101 

1020 DATA -2 

1030 DATA 5,6,7,45,666,77,89,17,3 

1040 DATA --3 

1050 DATA 3,4,5.6,7.8,3.01,5 

1060 RESTORE 'reset data pointer 

1070 READ A '-^-earch fr.r -2 

1080 IF AO-2 SOTO 1070 'read a9air, if not ~2 

1090 REM NOW POSITIONED AT SECOND LIST 

Figure 6-3. Using multiple DATA sets. 

where a search is made for —2, which is the second group of data. 
When —2 is found, the data in the second group can be accessed. 
Obviously, a -2 cannot be a DATA item anywhere in the DATA 
list, nor can any of the other values that are used for codes that mark 
the position. Clearly, we have reached the end of our list in noting 
the usefulness of the DATA, READ, and RESTORE commands. 
Let's move on to more useful data structures, but remember the 
DATA list as a powerful data structure for short programs, and, as 
we shall see, a means for initializing data in another data structure 
called an array. 



Array of Hope 

One of the more powerful data structures we have in Level II 
BASIC is the array. What's an array? Thought you'd never ask . . . 
an array is an ordered hst. The hst may be one-dimensional, two- 
dimensional, three-dimensional, or many-dimensional. The number 
of dimensions relates to how data in the list is accessed or obtained. 
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One-Dimensional Arrays 

A good example of a one-dimensional array is a shopping list. 
Wait a minute . . . didn't we go through this some other time? I have 
a feeling of deja vu. . . . Actually, the shopping hst presented eariier 
under DATA statements is a one-dimensional array, as are the other 
examples of DATA statements. The primary differences, however, 
are that the DATA statement produced a list of constant data that 
could not be modified and could not be easily accessed except in 
sequential fashion, starting from the beginning. A one-dimensional 
array, on the other hand, may be easily modified and accessed. 

As an illustration of a one-dimensional array, let's set up an array 
called AG (AGe) that will hold the ages of 100 people. The equiva- 
lent DATA statement approach would be 

100 DATA 33,50,12,2,7,105,969 

where the ages are known beforehand. (We have included Methu- 
selah's age for contrast. ) Using a one-dimensional array, though, we 
reserve space for the 100 ages by a DIMension statement. 



100 DIM AG(99) 

Note that the DIM statement specified an upper limit of 99. The 
number of items, or elements, in the array is 0-99 or 100. The num- 
ber specified in the DIMension statement is always one less than 
the number of elements in the array. 

When the BASIC interpreter encounters a DIM statement such 
as the one above, it reserves, or allocates, an area in RAM memory 
for array AG made up of 100 elements. What is in the elements? 
Initially, zeroes. It is up to the programmer to fill it with meaningful 
data. (That's usually the hardest part of programming.) 

The array is represented in Figure 6-4. It is stored in RAM mem- 
ory as a contiguous (consecutive) block, with the first element (0) 
at the start (lowest RAM) location, and the last element at the 
highest RAM location. Now let's fill in those elements with mean- 
ingful data. . . . 

To access any element in the array, we simply give the name of 
the array, AG, and a number from to 99 representing the array 
element. Of course, the number may be represented by a variable 
or expression, also. To INPUT a number of ages and fill in the array, 
for example, we can execute the code shown below. 



3000 CLS 

3100 1=0 

3200 INPUT "ENTER AGE"; A 

3300 AG(i:)=A 

3400 1=1+1 

3500 GOTO 3200 



clear- screen 
' iridex=0 
p 'input age in Yean 
I 'store in arrav 

I'lnt to next arrav 
:> for next a9e 



L.: 
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LOWEST 
RAM ADDRESS 



AG(0) 
AG(1) 
AGf2) 



HIGHEST 
RAM ADDRESS AG(99) 



100 ELEMENTS 
OF AG(e) ARRAY 



Figure 6-4. Example of one-dimensional array. 

This code will fill array AG forever, especially since there is no 
provision for ending the INPUT process. Initially, I is set to 0, and 
the first entry is made by AG(0)=A after A has been set equal to 
the INPUT value. Each time through the loop, I is incremented by 
one to point to the next element of the array. If more than 100 en- 
tries are made, a "BS ERROR" or 'Tjad subscript" results. 

To access any element of the array, all that's necessary is to specify 
AG(n), where n is any value to 99. To find the 50th age, for exam- 
ple, we may say 

100 B=AG(49) 'get 50»h age 

Look It Up in the Index 

Arrays group similar items of data, and the elements of one-dimen- 
sional data are accessed using an index value. In the case of the age 
array above, the index of 0-99 represented the number of the age 
entry. The first entry was at AG(0), the next at AG( 1), and so forth. 
This positional index is always maintained in arrays and makes them 
much more powerful than DATA lists, where data is accessed in se- 
quential fashion from beginning to end. In the age array above, we 
stored the ages in sequential fashion as they were received. In many 
cases, however, the position in the array is related to other than 
chronological order. Suppose that we had a 100-element one-dimen- 
sional array representing ages from to 99 years— DIM AG (99) 
( you old-timers don't get riled up, now! ) . We could tabulate a count 
of ages by incrementing the proper array element (corresponding to 
an age) quite easily as shown below. 
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4B00 CLS 

41BB INPUT "ENTER AGE";A 
4200 AG<A)=AG(A)+1 
4300 SOTO 4100 



' ■: 1 ear screen 
' irrput age 

etirerit a9e courit 



tirrpu 
' 1 n c r 
' 1 ,-..-,[= 



Here again, no check is made for a terminating condition. Also, no 
check is made for an out-of-range subscript, although the BASIC 
interpreter will give us a "BS" error if one is input. 

The idea of indexing is a very useful one, indeed. It allows re- 
lated data to be retrieved from a number of different arrays. Sup- 
pose, for example, that we have several one-dimensional arrays rep- 
resenting mailing-list data. An array called LN$ holds the last names, 
one called FR$ holds the first names, one called SA$ holds the street 
addresses, one called CT$ holds the cities, one called ST$ repre- 
sents the states, and one called ZP$ holds the zip codes. This arrange- 
ment is shown in Figure 6-5. If we require room for 100 names in the 
mailing list, we can allocate space by the statements 



5000 CLEAR 50B0 

5100 DIM LN$(991 

5200 DIM FR$<<'9) 

330B DIM SA«(99) 

5400 DIM CT!t<99) 

5300 DIM STS<99) 

S600 DIM ZP3i(99) 



clear- for- strings 
!ast name arra-,' 
first name arrav 
street address arrav 
cit--.' address arra-.- 
state address arra'r 
tTir. ZIP arr-a-T 



By splitting up the data on each entry in the mailing hst, we've 
accomphshed several things. First of all, we've made it easier to 
access each element of an entry in the mailing list. If we want to 
obtain the city, for example, we don't have to search a large string 
such as "PASCAL,BLAISE,123SORBONNE,PARIS,FRANCE,1623" 
to find "PARIS". Instead, we can simply pick up "PARIS" from the 
CT$ array with the proper index such as CT$(52). Secondly, we've 
made the speed of access faster. String manipulation is one of the 
slowest parts of any software. To anyone who has spent hours watch- 
ing a mailing-list sort only to have the line power go off about 3.2 
seconds from the end of the task, this is a large benefit. To print the 
mailing-list label, we can do 



6000 LPRINT FR$(I 1 :" 
6100 LPRINT SASd 1 
62B0 LPRINT CT$ (I ! !" 



'print first) last name 
'pRint street address 
';ZP3i(I) 'print ci t-vi statei ZIP 



Tables and the Boarding House Reach 

This is probably a good time to talk about tables. Tables are an- 
other type of data structure closely related to one-dimensional ar- 
rays. A good example of a table is a shopping list. (What? You say 
we've used this example eight times already?!) A table is, like a 
one-dimensional array, a collection of data arranged in convenient 
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Figure 6-5. Related one-dimensional arrays. 
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form. While we tend to think of arrays as being a list of very similar 
data (such as "states"), a table may have sub-groupings of data for 
each entry, and a master key. 

Let's take the mailing-list example and build a table to hold mail- 
ing-list entries. (Excuse me while I get a programmer's plane and 
some binary glue. . . . ) All right, a typical table is shown in Fig- 
ure 6-6. Each table is made up of entries. An entry is usually a fixed 
length-so many characters or bytes. Each entry may be broken 



TABLE 



FIRST TABLE ENTRY 



SECOND TABLE ENTRY 
THIRD TABLE ENTRY 



LAST TABLE ENTRY 



TYPICAL ENTRY 



CHARACTER 

CHARACTER 16 
CHARACTER 24 

CHARACTER 40 

CHARACTER 56 



LAST NAME 
(16 CHARACTERS) 



FIRST NAME 
(8 CHARACTERS) 



STREET 
(16 CHARACTERS) 



CITY 
(16 CHARACTERS) 



STATE 
(2) 



ZIP 
(5 CHARACTERS) 



FIELD 1 



FIELD 2 



FIELD 3 



FIELD 4 



FIELDS 5,6 



72 BYTES/ 

CHARACTERS/ 

ENTRY 



/ \ 
UNUSED(l) CHARACTER 60 

Figure 6-6. Table structure. 
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down into fields, each field representing a piece of data associated 
with the entry. One (or more) of the fields may be a key, which is 
the data item that is searched for. In this mailing-list example, the 
obvious key is last name, and related fields are first name, street, 
city, state, and zip code. Each field keeps the same relative position 
in the entry. 

One way to build the table is to use an array. Each element of 
the array will hold one entry, and the entire array will comprise the 
table. The array may be "initialized" to the standard length of 72 
bytes per entry (element) by a loop that sets up each element with 
dummy characters. 



90 CLEAR 8000 

100 DIM A$(99) '100 entries 

no FOR 1=0 TO 99 p ' set up loop 

120 A$(l) = STRING$(72,"*") ' fill with dummy characters 

130 NEXT I [_ ' loop 

Now we can use the string operators (LEFT$, MID$, etc.) to access 
the fields within each entry. If, for example, we wanted to change 
the street for the 13th entry in the table, we could perform the fol- 
lowing code 

1000 A$(12) = IEFT$ (A$(12), 24) + "NEW STREET *•****" + MID$ (A$(12),4U2) 

Note that every field must be padded out so that the entry remains 
at a length of 72 bytes to simplify access of fields in the general case. 
Tables may be fixed length or variable length. Fixed-length tables 
have a constant number of entries,- while variable-length tables have 
an open-ended number of entries. To find the start of any entry, we 
compute the entry number times the length of each entry to find a 
displacement, which is then used as a starting point to access the 
fields. Suppose that we have a fixed entry length of 72 characters 
per entry, and that 16 characters have been allocated to the last- 
name field, as shown in Figure 6-7. To find the location of the first 
name of the 51st entry, we would find the displacement of the en- 
try by 

50 X 72 = 3600 

and then add 16 to point to the first name. 

Cumbersome? Yes, and it's more diflBcult to work with tables in 
BASIC than other software levels such as assembly level since it's 
hard to keep things a fixed length. Bear in mind, though, that this 
type of data structure can be used when each entry can be made to 
be a fixed length and may prove to be useful some cold, dark night 
when you're bored with arrays and DATA lists. 
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ENTRY 



ENTRY 1 



ENTRY 50 



ENTRY LAST -1 



LAST ENTRY 



DISPLACEMENT = 50 ENTRIES* 
72 CHARACTERS/ENTRY = 3600 



LAST NAME 
(16) 



FIRST NAME 
(8) 



ADD 16 TO 

POINT TO FIRST 

NAME = 3616 



STREET 
(16) 



CITY 
(16) 



STATE 
(2) 



ZIP 

(5) 



Figure 6-7. Table use. 

Two Dimensions and Beyond 

One-dimensional arrays are pretty easy to visualize. So are two- 
dimensional arrays such as a chess or checkerboard, as Alice found 
out in Through the Looking Glass (Figure 6-8) : 

". . . and a most curious country it was. There were a number of 
tiny brooks running straight across it from side to side, and the 
ground between was divided up into squares by a number of 
little green hedges, that reached from brook to brook. . . ." 
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-^r 



Figure 6-8. A two-dimensional array. 



Two-dimensional arrays can be used to represent any two-dimen- 
sional condition, such as chessboards, a matrix of a screen or printer 
display, or a point on a graph. 

Taking the case of a chessboard, for example, we have a square 
configuration of 8 by 8 positions, for a total of 64 squares. We could 
use a one-dimensional array of 64 elements, numbered through 63, 
each one corresponding to one of -the 64 squares. However, in this 
case it is much simpler to relate a two-dimensional array to the 
chessboard as shown in Figure 6-9. 

Each of the squares is referenced by two values, representing the 
row and column, as shown in the figure. As the first element of the 
array is always numbered "0," the first square of the chessboard will 
be row and column 0. We could use an order of "row, column" or 
"column, row"; the choice is completely arbitrary. Whichever one 
we use, of course, must be maintained for any reference to the ar- 
ray. We will use a row, column orientation so that the upper left 
square is designated row 0, column 0, the next square (knight) is 
row 0, column 1, and so forth. 

Any time we want to refer to a particular position on the chess- 
board, we can find its row, column notation and then use the two 
values to reference a two-dimensional array. 

The array in this case is defined by 

100 DIM A$(7,7) 

Don't forget that in defining the array the value in the parentheses 
represents the maximum value of the array and not the number of 
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ROWO 
COLUMN 



O 



ROW 7 
COLUMN 



ROWO 
COLUMN 1 

1 







COLUMNS 

3 4 5 



ROWO 
COLUMN 7 











^ 






E 




r 



a 



ROW 7 
COLUMN 7 



Figure 6-9. Two-dimensional array for chessboard. 



elements. In this case, the array is 8 by 8, but the 'last" element is 
referenced by (7,7). 

Having defined the chessboard array, we can now reference any 
position by two values, row and column. To "initialize" the array 
to starting chess positions, we can use chess notation. 



200 DIM A$(0,0)="BQR" 
210 DIM A$(0,1) = "BQKT" 
220 DIM A$(0,2)="BQB" 

I 
I 
i 
I 

\ 
etc. 



'black queen's rook 
'black queen's knight 
'black queen's bishop 
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<s 
a. 



rt- CD 

o z 



o 



o 
o 



Z3 



II II II 

CD r-H CNJ 



Figure 6-10. Two-dimensional array for inventory. 
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Of course, a two-dimensional or other size array does not need to 
have a "physical" counterpart such as a chessboard. We can use 
arrays to represent more abstract variables. Suppose that we have 
an inventory of 100 parts, each with a part number of through 99. 
We can use a two-dimensional array to order the parts based on part 
number and "status." We'll let the second dimension be three values 
representing number on hand, number on order, and number re- 
quested, as shown in Figure 6-10. The DIMension statement for this 
array is 

100 DIM A(99,2) 

where 99 represents the 100 parts and 2 represents the three "status" 
indices of for number on hand, 1 for number on order, and 2 for 
number requested. 

To find the number on hand for part number 55 (a left-hand- 
threaded blidgit), we'd use 
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20 COLUMNS (X) 
8 9 10 11 


12 


13 


14 


15 


16 


17 


18 


19 





0.0 


1,0 




































19,0 


1 


0,1 








































2 








































3 










































4 










































5 










































6 










































7 










































8 










































^ 9 










































|io 










































S 11 










































12 










































13 










































14 










































15 










































16 










































17 










































18 










































19 


0,19 






































19,19 



Figure 6-11. Life two-dimensional array. 
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200 B=A(55,0) 

while 



'find number on hand 



210 B— A(55,1) 'find number on order 

would find the number on order, and 

220 B=A(55,2) 'find number requested 

would find the number requested. 

One of the more fascinating numerical games to appear in recent 
years is the game of Life. Life is very simple in concept but (as they 
say, ominously) has far-reaching implications. Life is played on an 
infinite two-dimensional array checkerboard. Since it's rather hard 
to fit an infinite array into a finite space (even in 48K), we'll limit 
it to an array about 20 by 20. Each cell of the array can be defined 
by a row and a column, as shown in Figure 6-11. 

The rules of the game of Life are: We start off with some arbi- 
trary pattern on the array, such as the one shown in Figure 6-12. 

INITIAL 
PATTERN 















r 








/ 


/• 


'^y 


^ 




// 


/z. 








M 


V 









"DEAD" CELLS 
ARE BLANK 



CELLS 



Figure 6-12. Life example. 



Each cell is living (on) or dead (off). On the next generation, 
whether a cell lives or dies depends on its neighbors. If it has fewer 
than two neighbors, the cell dies from loneliness. If it has 4, 5, 6, 7, 
or 8 neighbors, the cell dies from overcrowded conditions. If a cell 
has 2 or 3 neighbors, it survives to the next generation. In addition, 
if any cell is dead and the number of neighbors is 3, then a new cell 
is born on the next generation. These rules are shown in Figure 6-13. 
The game proceeds from generation to generation, and it's fasci- 
nating to watch whole colonies appear, die, spawn new patterns— in 
general to watch a process analogous to . . . well . . . life! ( Based on 
its interest, since 1975 Life has probably burned up hundreds of 
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EXAMPLE 

e m- mm ® ® 

#®® #• ® ® @ ® 

9 <B ® ® ® 

GENERATION 1 GENERATION 2 GENERATIONS GENERATION 4 

RULES 

(0) 

m EVERY CELL WITH NO NEIGHBORS DIES ON NEXT GENERATION FROM LONELINESS. 

m 9 EVERY CELL WITH ONLY ONE NEIGHBOR DIES. 

(2) (2) 

12) A CELL WITH TWO NEIGHBORS SURVIVES. 
® 

(3) (3) 
@ ® 

(3) (3j A CELL WITH THREE NEIGHBORS SURVIVES. 
@ 9 

(3) (5) (3) 
® @ ® 

® ® ® A CELL WITH FOUR OR MORE NEIGHBORS DIES FROM OVERCROWDING. 

(3) (4) 

® # 

(II (2) (1) 

® ® ® AN EMPTY CELL WITH EXACTLY THREE NEIGHBORS IS A BIRTH CELL. 

(3' A NEW BIRTH OCCURS ON THE NEXT GENERATION. 

O 

Figure 6-13. Life rales. 

millions of dollars worth of computer time on expensive computers. ) 
If you're interested in finding out more about Life (and there are 
many subtleties), you can find material in hobbyist computer maga- 
zines and back issues of Scientific American. 

To set up our Life game, we'll use two arrays, one for the current 
generation, and one for the next. This is a slow way to implement 
the game, but it will allow us to do some manipulation of two-dimen- 
sional arrays. The program is shown in Figure 6-14. ( How 'bout an 
exercise for you: Speed up the operation 100-fold.) 

The arrays are called A and B and are defined by the DIMension 
statements DIM A (21,21) and DIM B( 19,19). A is an array of 484 
elements, 22 on a side, while B is an array of 400 elements, 20 on a 
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10 

20 

30 

40 

100 

110 

120 

130 

200 

210 

220 

230 

240 

250 

300 

310 

320 

330 

340 

330 

360 

370 

380 

390 

400 

410 

420 

430 

440 

450 

460 

500 

S10 

520 

330 

540 

550 

560 

570 



CLS 

DIH A(21>21 1 

DIM B<19, 1<?) 

GE=1 

INPUT XiY 

IF X=-l SOTO 500 

B(X>Y)=1 

SOTO 100 

FOR X=0 TO 1<? 

FOR Y=0 TO 19 

A<X+1,Y+1 i=B(X>Y> 

B(X,Y1=0 

NEXT Y 

NEXT X 

FOR X=0 TO 1«? 

FOR Y=0 TO 19 

NO=0 

IF A<X>yi=l NO=NO+1 

IF A(X+1,Y1=1 N0=N0+1 

IF A(X+2.Y)=1 NO=NO+1 

IF A<X,Y+1)=1 N0=N0+1 

IF A<X+2iY+l) N0=N0+1 

IF A<X,Y+2)=1 N0=N0+1 

IF A<X+1,Y+2)=1 N0=N0+1 

IF A(X+2,Y+2)=1 N0=N0+1 

IF NO=a OR No=i B(x.y)=a 

IF N0=4 OR N0=5 OR N0=6 OR N0=7 
B(X,Y)=A<X+1,Y+1 1 
B(X.Y1=1 



'set 
'set 



r' 



creerc 

UP large arrav 

:up ujorking arr-av 

tialise generation 

input initial pattern 

go if input finished 

set eel 1 

go for next input 

horizontal loop 
~ 'vertical loop 

'adjust for- array sizes 
'zero lyorking arrav 

' 1 OOP 

loop _^___ 

loop for computation 
-'horiz and vert 
'init # of neighbors 



PARTI 



PART 2 



PARTS 



PART 4 



IF N0=2 

IF N0=3 

NEXT Y 

NEXT X 

PRINT a B96> "GENERATION" ;GE 

FOR X=0 TO 19 

FOR Y=0 TO 19 

IF B<X,Y)=1 SET (X+54,Y+14) ELSE 

NEXT Y 

NEXT X 

SE=GE-H 

GOTO 200 



OR N0=8 B(X,Y)=0 



"-• loop 

'- • 1 OOP 



r 'setup for displav 
p ' tuo nested loops 
RESET(X+54,Y+14) 
I "-'loop 

"continue tuith loop 
'burtip 9eneratioN count 
■"continue with n e >; t 9 e n 



PART 5 



Figure 6-14. Life program. 

side. The periphery of A is never used and al-ways contains zeroes. 
A always contains the current generation, -while B contains the next 
generation. The program is made up of five parts. Part 1 initiahzes 
the two arrays and sets variable GE to 1. GE is the "generation" 
counter and increments by 1 for each generation. 

Part 2 allows the user to input an initial pattern. A good one to 
try is the "R pentomino" pattern of 10,11; 11,10; 11,11; 11,12; 12,10. 
The form of the input is x,y, where x is the horizontal coordinate 
for the array of to 19, and y is the vertical coordinate of to 19. 
Inputting a -1,0 terminates the input. After inputting the initial 
data, array B has been set to a one for every cell specified. A GOTO 
part 5 prints array B by displaying it in the center of the screen. As 
the screen center is at x=64 and y=24, the upper left-hand corner of 
the array area will be at x=54, y=14. The cells in the B array are 
converted to screen coordinates by the SET and RESET commands 
which look at every element of the B array and either set or reset 
a screen point. 

Normally, the flow is part 3, part 4, part 5, and back to part 3 
again. Part 3 transfers the last generation in the B array to the A 
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# 



NO = NUMBER OF NEIGHBORS 



CIRCLED CELL HAS 1 NEIGHBOR 



CIRCLED CELL HAS 2 NEIGHBORS 



• • 



(®) 



CIRCLED CELL HAS 3 NEIGHBORS 



• • • 



• (®) 



CIRCLED CELL HAS 4 NEIGHBORS 



• • • 

• (•) • 



CIRCLED CELL HAS 5 NEIGHBORS 



• (•) • CIRCLED CELL HAS 6 NEIGHBORS 

• • • 

• (•) • CIRCLED CELL HAS 7 NEIGHBORS 



• • • 

• (®) • CIRCLED CELL HAS 8 NEIGHBORS (MAXIMUM) 

• • • 



Figure 6-15. Life computation. 
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array. The boundary of the A array is not used, so the A array really 
starts at x=l, y=l. 

Part 4 is the heart of the program that computes the next gener- 
ation. Every cell in the A array now contains the last generation. 
The program looks at every cell in the active area of A and computes 
the number of neighboring cells (NO), as showm in Figure 6-15. 
Each cell in B is set according to the number of neighbors in the 
corresponding A cell, according to the Life rules. If NO is 2, the 
B cell is set to the same value as the A cell. If NO is 3, a "birth" 
occurs in the B cell. At the end of the computation in part 4, part 5 
is entered so that the B array can be printed. Parts 3 through 5 are 
then repeated for the next generation. 

The Life program is a good exercise in array manipulations. We 
actually translated one array (B) to a new position in the A array. 
In addition, we converted the B array to a third two-dimensional ar- 
ray, the screen. Note that the screen display is really a "hardware" 
array of 128 by 48 points when we are in the graphics mode. 

This version of Life could be speeded up considerably by using 
only one array and by scanning for empty "horizontal" and "verHcal" 
Imes. (Oops— didn't mean to give away any secrets for your exercise. 

We've seen one-dimensional arrays and two-dimensional arrays, 
but how about three dimensions and above? Level II BASIC permits 
any dimension of array, and in fact multi-dimensional arrays can 
easily be used for mathematical problems such as computing three- 
dimensional vectors. For non-mathematical processing, however, it 
does get rather hard to visuaUze arrays above three dimensions. The 
physical appearance of one-, two-, and three-dimensional arrays is 
shown in Figure 6-16, along with their corresponding DIMension 
statements. 

About the only restriction on the use of arrays is their size. Large 
areas will gobble up a great deal of memory in a very short time, 
especially if the array variables are types that occupy a large number 
of bytes. A three-dimensional array that is 20 by 20 by 20 and uses 
integer variables DIM A% ( 19, 19, 19 ) , for example, will use 20»20» 
20 2 or 16000 bytes for the body of the array plus 12 more for pa- 
rameters to describe the array. The same array using single-precision 
variables (the default variable type) would be twice as large-32,012 
bytes! You might want to investigate the storage requirements of ar- 
rays by changing the DIMension statement in the program below 
and RUNning the program with various DIMensions. 

100 A=MEM 

no DIM A%(19,19,19) 

120 PRINT "ARRAY USED ";A-MEM;" BYTES" 

119 



DIM A(8) 






9 9 ELEMENTS 



ONE-DIMENSIONAL 

7 



DIM A(3.6) 
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TWO-DIMENSIONAL 



DIM A(4,6,l> 
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7 
THREE-DIMENSIONAL 
Figm-e 6-16. Three common array models. 

Initializing Arrays 

Early in this chapter, we mentioned that arrays could be initialized 
by using data from DATA lists. This is an excellent usage of both 
DATA statements and arrays and is quite common. The DATA state- 
ments are used to hold all of the initial data for program arrays in 
any convenient order. One massive READ operation at the beginning 
of the program goes through the DATA list and initiahzes all arrays 
in the program that require a starting set of values. Since this is done 
only at the beginning of the program, the initiahzation process may 
be as compHcated as required; thereafter, the arrays hold the proper 
data and may be accessed in their normal "random-access" fashion. 
Many programs from this point on will illustrate this procedure. 
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CHAPTER 7 



The Search for Better Data 
and Sorting It All Out 



In this chapter, we'll continue the saga of the "Data Structure 
Conspiracy." When we last left Ernie List (mild-mannered pro- 
grammer known only to a select few as -kDATAMANir), he was 
fighting his way out of a diabolical matrix constructed by his arch 
enemy. Dr. Dimension. 

In today's episode we'll follow the adventures of Dataman as he 
searches for the missing data and then attempts to sort it all out . . . 

Although sometimes one wishes there was a real Dataman to or- 
ganize and search for data, the techniques discussed in this chapter 
should help define the ways in which data is organized and accessed. 

Unordered Data— No Order At All 

One way to order data, of course, is to not order it at all. The data 
is simply dumped into an array as it comes in. There are certain 
advantages to this if the number of data elements is small or if the 
data is actually ordered on the basis of appearance. If the number 
of data elements is large, however, it takes quite a length of time 
to find a particular data element. To illustrate data ordering, search- 
ing, sorting, and merging (sounds like a stock brokerage, eh?), we'll 
use the "Standard" data list shown in Table 7-1. This is simply a 
typical list of data that must be processed. Because much of the 
processing of this type involves alphanumeric data, we've made the 

121 



data string data, although numeric data could just as easily have 
been used. 

The order in Table 7-1 appears to be unordered, but there is a 
definite order-that of size. If we were working with a list according 
to size, then this indeed would be an ordered list. From the stand- 
point of an alphabetical list, however, the standard list is unordered. 



Table 7-1. "Standard" Data List Unordered 



ELECTRON (PART OF OUTPUT TO CASSETTE) 

LA SMOG {PARTICULATE AAAHER) 

DIAMOND (20 POINTS) 

PEA (FROM 1971 POLITICAL FUND RAISING DINNER) 

AAARBLE (SHOOTER) 

#3 BALL BEARING (FROM SANTE FE REEFER CAR) 

FABERGE EGG (FROM HERMITAGE) 

BASEBALL (PETE ROSE AUTOGRAPH) 

ORANGE (ONE OF THREE) 

BOWLING BALL (USED FOR PERFECT 150 GAME) 

BALLOON (WITH THE WORDS "THE TRS-80 IS A GAS") 

BALL OF STRING (IN BEDROOM) 

747 TIRE (SOUVENIR OF HAWAII TRIP) 

DOUGHNUT (SIGN AT DRIVE-IN) 

GOODYEAR BLIMP (WITH ANIAAATED SIGN) 

PERISPHERE (AT 1939 WORLD'S FAIR) 

RAAAA (IN CLARKE ORBIT) 

PHOBOS (ONE OF TWO) 

AAARS (A PLUG FOR FUNDING) 

EARTH (IS THERE INTELLIGENT LIFE HERE?) 



Much of the time, we will be working with alphabetically ordered 
Usts in data processing on the TRS-80, although, as we see from the 
example, the order may be based on parameters such as employee 
number, zip code, disk track and sector number, or others. 

In this chapter, we'll be comparing some of the different tech- 
niques used to find data and to order it, so it will be convenient for 
us to have a "standard" way of timing the techniques. Another word 
for the techniques or approaches to a problem is "Algorithm" {de- 
rived, believe it or not, from Al Khwarizm, a ninth century Arabic 
mathematician). Searching and sorting are some of the slowest pro- 
cesses in BASIC and other types of programming since the amount 
of data to be searched is usually very large and the search involves 
time-consuming (string) comparisons. With a standard list of 20 
items, however, the searches can't take too long. . . . 

The code below slows down the search or sort by a one-second 
delay between comparisons and displays the current item in the 
list being investigated. It is in the form of a subroutine which we'll 
call for different searching algorithms. 
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100 CLS -clear screer, 

Jig DIM A«(20) _ .array for- data 

120 FOR 1=0 TO 19 r •-«*>"• for data tr. 

130 READ Bi. ,r-ead data i tarn 

140 A*(I)=B» .„,ove to arrar 

150 NEXT I l-.c^,^,,^^„^^ ^^1 ^^^,^ 

160 INPUT "ITEM FOR SEARCH" !C$ "inPut item to be four, 

fZ2 Sir^ 'clear screen 

1S0 FOR 1=0 TO <? r' setup loop for di». 

190 PRINT TABOJ ;I;AS(I) ;TAB(40) ;I + 10;AS(I + 10) 



200 NEXT I 



"'loop 



'print action 

'9o If found 

'not found) contl nue 



210 FOR 1=0 TO 19 r' setup loop for search 

220 GOSUB 20000 

230 IF CS=AS(I) GOTO 270 

240 NEXT I 

2S0 PRINT 3896, " ITEM NOT FOUND 

260 GOTO 260 Moop here 

270 PRINT a a96i»ITEM FOUND AT "!l:" 

2B0 SOTO 280 -loop here after find 

300 DATA "ELECTRON". "LA SMOG" , "DIAMOND" . "PEA" , "MARBLE" 

310 DATA "(t3 BALL BEARING" , "FABERGE EGG" , "BASEBALL" . "ORANGE" , "BOWLING BALL" 

320 DATA "BALLOON", "BALL OF STRING", "747 TIRE" , "DOUGHNUT" , "GOODYEAR BLIMP" 

330 DATA "PERISPHERE", "RAMA", "PHOBOS", "MARS", "EARTH" 

20000 PRINT a 896, "TESTING ENTRY « "!I 'print te'st action 

20010 FOR J=0 TO 100 -delav loop 

20020 NEXT J 'loop 



20030 RETURN 



return to calling program 



Figure 7-1. Sequential search of unordered list. 



20000 REM A HAS ENTRY # 'for display 

20010 PRINT @ 896,"TESTING ENTRY # ";A 'message 

20020 FOR 1 = TO 100 r ',i„ing loop 

20030 NEXT I L 'continue 

20040 RETURN '„turn 

The time required to search for a given entry in an unordered list 
varies. At best, the sought entry is the first entry; at worst, it is the 
last entry of the list. The average number of comparisons that must 
be made in an unordered Ust is Vz the number of entries in the hst. 
In the case of our "standard" list, the average search would involve 
testing about ten entries. 

The code in Figure 7-1 iniHaHzes a string array A$ with the twenty 
string items (without comments) and then illustrates the searching 
process for an unordered list. 

The search time to find a particular data item is quite short for 
this; we even had to slow it down for a reasonable display. If the 
timing loop in the 20000 subroutine is taken out, however, you can 
see that about one second is required to search the entire unordered 
list for a data item that is not in the Hst. If the list is hundreds of 
items long, it is easy to extrapolate and calculate that a hnear search 
of an unordered list may take several minutes. If we have a great 
deal of repetitive searching to be done, say searching for items in an 
inventory, the entire task could become very time-consuming. 

Ordered Lists 

It behooves us, then, to try to reduce the search time. The first 
step in doing this is to order the hst we have to search. In the case 
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of much data that we process in TRS-80 BASIC, this order will be 
alphanumeric. Well, that's easy enough-we'U just alphabetize every- 
thing. But what about the "#" character and digits such as "7"? 

There is a definite order to all string data in Level II BASIC. Its 
order is defined by the ASCII character set used by Level II BASIC. 
The character set for character codes 32 through 127 is shown in 
Table 3-1. In an extraterrestial telephone directory ordered accord- 
ing to these codes, a plasma drive mechanic with the last name of 
%ZZK will appear before a Zarful-dog trainer by the name of 
&ANDER-SON. Names prefixed by lower-case letters such as an 
itinerant Welshman by the name of "apRoberts" appear after "ZZZ 
Tailors." Blanks or spaces, when used, will appear before just about 
anything else; ROBERTS ED will come before ROBERTS,ED. It's 
somewhat important to know the order of things so that there are 
no unpleasant surprises when the computer generates a hst based 
on the weights of the ASCII codes used. 

When data is according to lower-valued items first, it is ordered 
in ascending order. There is no reason that we cannot have other 
orders, such as descending order, but we'll use ascending order in 
all of the examples here. Table 7-2 gives our standard list in ascend- 
ing order. 

Table 7-2. "Standard" Data List Ordered 



#3 BALL BEARING 

747 TIRE 

BALL OF STRING 

BALLOON 

BASEBALL 

BOWLING BALL 

DIAMOND 

DOUGHNUT 

EARTH 

ELECTRON 

FABERGE EGG 

GOODYEAR BLIMP 

LA SMOG 

AAARBLE 

AAARS 

ORANGE 

PEA 

PERISPHERE 

PHOBOS 

RAAAA 



Now that all is in order, how do we efficiently search an ordered 
list? Right away we're in better shape than with the unordered Ust 
when we're dealing with data items that are not in the list. In the 
case of the unordered list, we had to search the entire Ust to deter- 
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mine that a data item was not in the hst. For a twenty-item Hst this 
meant twenty comparisons. When we have an ordered list, we only 
need to search forward in the hst until we find an item whose weight 
is greater than the item for which we are searching! This amounts 
to comparing the input string with the string from the hst and end- 
ing the search if the list string < input string. 

The average search for an equal distribution of items in the hst 
and items not in the list will be a search of about ten items. The 
average search through an unordered list will be about fifteen items. 
This linear search of an ordered list is shown in Figure 7-2. 



100 CLS 'clear screen 

lia DIM A*(2B) 'arrar for data 



'setup for- data to arrav 
'read data item 
'move to arraY 
'continue til done 



120 FOR 1=0 TO 19 

130 READ BS 

140 A«<i;i=B* 

150 NEXT I 

160 INPUT "ITEM FOR SEARCH" :C* 'input item to be found 

170 CLS 'clear screen 

ISO FOR 1=0 TO 9 r' setup loop for displaY 

190 PRINT TAB<5) !I!A*(I) :TAB(40) ;I + !0;A«<I-H0) 

200 NEXT I •-' loop 



'setup loop for search 

'print action 

'90 if found 

'9o if past logical poi 

'not found) continue 



210 FOR 1=0 TO 19 

220 GOSUB 20000 

230 IF C$=A*<I) GOTO 270 

235 IF C3.<A3;(I) SOTO 250 

240 NEXT I 

250 PRINT S896,"ITEM NOT FOUND 

260 GOTO 260 'loop here 

270 PRINT a S96> " ITEM FOUND AT • ; I ; " 

280 GOTO 280 'loop here after find 

:i00 DATA "«3 BALL BEARING" < "747 TIRE". "BALL OF STRING" , "BALLOON" , "BASEBALL" 

310 DATA "BOWLING BALL" . "DIAMOND" . "DOUGHNUT" , "EARTH" . "ELECTRON" 

320 DATA "FABER6E EGG" . "GOODYEAR BLIMP". "LA SMOG" , "MARBLE" , "MARS" 

330 DATA "ORANGE". "PEA". "PER I SPHERE ". "PHOBOS"." RAMA" 

20000 PRINT a B96! "TESTING ENTRY # "!I 'print test action 

20010 FOR J=a TO 100 'delaY loop 

20020 NEXT J ' 1 OOP 

20030 RETURN 'return to calling program 

Figure 7-2. Sequential search of ordered list. 

We could extend the idea of testing whether a list item is greater 
than the search item further by taking every, say, fifth item and 
doing a comparison on the hst item and sought item. We could 
then find out in a series of four steps in which general area of the 
hst it was. Then we could do a sequential search of that subgroup. 
This would save considerable time on a long list. What is the ulti- 
mate extension of this idea? Take off your shoes, hght yoiu- pipe, 
and I'll recount a tale of adventure and intrigue I learned in the 
Mediterranean. . . . 

The Binary Search Mystery 

Do you remember the paradox of Z;eno and the Tortoise ... or 
was it Aristotle and the Hare? In any event, if you start off travehng 
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toward your front stoop from the sidewalk, and once each second 
you go Vz the remaining distance, how long will it take you to ar- 
rive at the stoop? Well, to make a long story short, although each 
second the distance is decreased by one-half, you will never arrive, 
as you take shorter and shorter steps. With luck, our search does 
arrive, but the idea is somewhat the same. In the binary search, the 
range to be searched is halved for each step, or iteration, of the 
search. 

Let's see how this works. Suppose that we take our "standard list" 
and search for "MARBLE" as shown in Figure 7-3. We know the 

INPUT ITEM = "MARBLE" 



1 


#3 BALL BEARING 








2 


747 TIRE 




3 


BALL OF STRING 




4 


BALLOON 




5 


BASEBALL 




6 


BOWLING BALL 




7 


DIAMOND 




8 


DOUGHNUT 




9 


EARTH 


® . 


10 


Fl FCTRON 


11 


FABERGE EGG 




•^ 


® 


12 


GOODYEAR BLIMP 




, — 1 


13 


LA SMOG 


<n 


2s: 


■=»■ 


14 


MARBLE 


1 — i 


^— X 




15 


MARS 


^ 


© 


16 


ORANGE 


S 


V — y 


17 


PEA 


\— 




18 


PERISPHERE 






19 


PHOBOS 






20 


RAMA 









® 



(T)FIRST COMPARISON AT ITEM 10. 

"ELECTRON" < "MARBLE," SO NEW RANGE IS 11-19. 

(2)SEC0ND COMPARISON AT ITEM (19-ll)/2 -h 11 = 15. 
"MARS" > "MARBLE," SO NEW RANGE IS 11-14. 

(?)THIRD COMPARISON AT ITEM (14-ll)/2 -f-ll = 12. 

"GOODYEAR BLIMP" < "MARBLE," SO NEW RANGE IS 13-14. 

(?)F0URTH COMPARISON AT ITEM (14- 13)/2 + 13 = 13. 

"LA SMOG" < "MARBLE," SO ITEM MUST BE AT 14 (OR NOT IN LIST). 

Figure 7-3. Binary search algorithm. 
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list is twenty items long. We'll search first midrange at item 10 and 
compare the input item with the list item. The list item is less than 
the input item, so we know that the item must be in the upper Va 
of the list, items 11-19. We'll split that range at 15 and compare 
again. This time item 15 is greater than the input item, so we know 
that the sought item is in the % of the list from 11-14. The next 
comparison is made at 12, where the hst item is less than the input 
item, making the next range 13 to 14. At 13, the list item is still less 
than the input item. The list item is therefore at item 14 ( or is not 
there at all!). 

This search is called a binary search and is one of the most effi- 
cient searches for long lists of ordered data. The maximum number 
of comparisons { or iterations ) that must be performed is represented 
by the power of 2 that results in a number greater than the number 



100 CLS .clear screen 

Ji2 512 ?*120) _ 'arrar for data 

setup for data 



'read data item 
'move to array 
continue tiT do 



120 FOR 1=0 TO 19 

130 READ B$ 

140 A$(I)=B5 

150 NEXT I 

J60 INPUT "ITEM FOR SEARCH" ;C$ 'input item"to"be 

170 CLS 'clear screen 

1B0 FOR 1=0 TO 9 r'setup loop for di-plav 

170 PRINT TAe(5);I;A3i<I):TAB<40);I + 10,-A$(I + lB) 

200 NEXT I I-' loop 

202 HI=20 'initialize hi item 

onA , 1^ ■initialize lo item 

Z^t I'l r^ 'initialize middle item 

20S FOR IC=0 TO 4 

209 SOSUB 20000 



-'item must be fnd in 
'display action 
'9o if found 
'pick 1/2 remaining 
'find new midpoint 
'continue loop 



210 IF A*!1)=CS GOTO 270 

212 IF Mdxa THEN LO=I ELSE HI = I 

214 I=INT( <Hl-L0)/2)+L0 

216 NEXT IC 

250 PRINT aB96i"lTEM NOT FOUND 

260 GOTO 260 -|oop here 

270 PRINT a 896, "ITEM FOUND AT »;I:" 

280 GOTO 2B0 - , „,p ^^pe after find 

300 DATA "tt3 BALL BEARING" , "747 TIRE". "BALL OF STRING" . "BALLOON" , 

310 DATA "BOWLING BALL" , "DIAMOND" , "DOUGHNUT" . "EARTH" . "ELECTRON" 

320 DATA "FABERGE EGG" , "GOODYEAR BLIMP", "LA SMOG" > "MARBL"^" , "MAR^;" 

330 DATA "ORANGE", "PEA", "PERISPHERE"."PHOBOS", "RAMA" 

20000 PRINT S B96, "TESTING ENTRY # "U 'print test action 

20010 FOR J=0 TO 100 'dela- loop 

20B20 NEXT J • ,,-,,-,„ 



20030 RETURN 



' return to cal 1 in9 



Figure 7-4. Binary search. 

of items in the list. For example, if a list has 150 items, then 2^ is 
the next power of 2 larger than 150 (28 = 256). The power of two 
is 8; therefore, a binary search will take 8 iterations to find out where 
the item is in the ordered hst, compared to an average of 75 for a 
sequential search! The binary search is therefore quite powerful and 
very efficient. 

Let's see how this works in a practical example. Figure 7-4 shows 
a binary search for our standard Hst. The number of iterations here 
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is determined by 2^, which is 32, the next power of two greater than 
the size of the list, 20. The number of iterations is therefore 5. We've 
set up a loop to go through 5 iterations at the end of which the input 
string has not been found in the hst. If the string is found, then the 
loop is exited. Running the program in Figure 7-4 illustrates the 
approximate speed of die binary search. For small lists, the "over- 
head" of the additional string comparison is significant, but you will 
find that as lists become longer and longer, it becomes less and less 
of a factor. 

There are other searching algorithms (as a matter of fact, there 
are literally books full of them), but the sequential search and bi- 
nary search are two of the most common techniques employed in 
BASIC programming. 

Algorithms of a Different Sort 

In the previous discussion, we've assumed that our list of items 
to be searched was ordered. How do we order the list in the first 
place? In the next few pages, we'll compare the ways in which data 
can be sorted. Here, as in searching, there is enough descriptive 
material on sorting to fill the national archives, but we'll consider the 
most common techniques for BASIC. 

Suppose that we go back to our standard unordered list from 
Table 7-1, and order it by several methods. The first method that 
comes to mind is to sort the list using two arrays. We could go 
through the first array (the hst) and look for the smallest item. 
After scanning the entire list, we now have the smallest item, which 
can be put into the next element of the second array. Next, we would 
look for the second smallest item, and so forth, until all of the items 
from the unordered array have been moved to the sorted array. This 
process is shown in Figure 7-5. 

The code for this sort is shown in Figure 7-6. This is a demon- 
stration program that displays the data in both arrays as the sort 
occurs. The main loop in the program starts off with the first entry 
in the Hst array A$. This loop first looks for a "non-blanked" entry. 
(As each entry is moved from the first array to the second array, it 
is blanked by a string of "<» = «*«".) if it cannot find the next (0 to 
19) non-blanked entry, the sort is done. If it does find a non-blank 
entry, then it scans the remainder of the array for a data item smaller 
than the current data item. If one is found, then the new item be- 
comes the smallest. At the end of the scan, the smallest item remain- 
ing is transferred to the second array and then blanked in the first 
array. This process continues until aU items have been transferred. 
This "two-buffer" sort is perhaps the slowest of all sorts, but it is 
direct and easy to code. 
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BALL OF STRING 








747 TIRE 
DOUGHNUT 


) 








GOODYEAR BLIMP 






PERISPHERE 






RAMA 






PHOBOS 






MARS 






EARTH 











BUFFER 1 (ARRAY 1) 
(UNSORTED) 



BUFFER 2 (ARRAY 2) 
(BUILT UP FROM 
BUFFER 1 DATA) 



Figure 7-5. Two-buflEer-sort algorithm. 



90 CLEAR 1000 

100 DIM AS<19) 

200 DIM B$<19) 

300 FOR 1=0 TO 19 

A00 READ C« 

500 A*<I)=C* 

600 B*( I ) = "»»»*" 

7B0 NEXT I 

1B00 K=0 

1100 FOR 1=0 TO 19 

1700 IF A»( I )="««»«" SOTO 2500 

1800 FOR J=l TO 19 

1900 IF A»(J)="»«««" GOTO 2100 

2000 IF A»(J)<A«(I) THEN I=J 

2100 NEXT 3 

2200 B«(K)=A«(I) 

2300 A»( I )="****" 

2400 K=K+1 

2405 CLS 

2410 PRINT TAB(5)."A» ARRAY" , TAB (40) , 



'allocate Etring storageE 
'al 1 ocate unsorted array 
'allocate tuorlcing arrav 

"'setup loop for initial izatic 
'read data item 
'store in arrav 
'mark b$ arrav entry unused 
*~ ' 1 OOP 

'initialise b$ index 

"'outer loop for nxt entry 
'9o If unused 

•'loop for smallest 
'go if unused 
' new smal 1 est 
*— ' loop 
'make entry xn t>$ 
'mark unused 
'bump b$ index 
'clear screen 
"B* ARRAY" 

for display 
ret contents of arrays 



CI OOP 
' print 
* 1 OOP 



2415 FOR L=0 TO 19 

2420 PRINT TAB(5),A$<L),TAB<40),B*(L) 

242S NEXT L 

2430 I=-l 'start from beginning 

2500 NEXT I L.g„ ,.^^. ^,^,,^ ^^,^^.^, 

2600 PRINT "SORT DONE" 'end message 

3000 DATA -ELECTRON". "LA SMOG" , "DIAMOND" ," PEA" , "MARBLE" 

3100 DATA "tt3 BALL BEARING" , "FABERGE ES5" . "BASEBALL" . "ORANGE" ■ "BOWLING BALL' 

3200 DATA "BALLOON", "BALL OF STRING". "747 TIRE" . "DOUGHNUT" , "GOODYEAR BLIMP" 

3300 DATA "PERISPHERE", "RAMA". "PHOBOS", "MARS". "EARTH" 



Figure 7-6. Two-buffer sort. 
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Rising With the Tide 

Another of the disadvantages of the two-buffer sort is that a great 
deal of memory is required-twice that of the unsorted Hst. The sort 
we'll talk about here-the bubble sort-requires only the memory for 
the unsorted list itself. The separate elements of the Hst are moved 
around within the Hst until they are ordered from beginning to end. 
Because the lower-weighted or "lighter" elements "bubble" to the 
top, the name "bubble-sort" is very descriptive. The algorithm works 
as shown in Figure 7-7. Starting from the beginning of the Hst, each 
item (I) is compared with the next item (I+l). If the next item is 
of lower weight, the two items are swapped so tbat the lower- 



One Pass Through a Bubble Sort of 9 Data Items 
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6 
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^-^ I )SWAP 
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N:M "N compared to M" 
Figure 7-7. Bubble-sort algorithm. 

weighted item rises to the top. This process continues until the end 
of the list is reached. The program then goes back to the beginning 
of the list and repeats the process. All items in the Hst have been 
sorted when a complete pass is made through the list without any 
swap of items having occurred. 

Figure 7-8 shows a bubble sort implemented in our usual grand- 
stand display mode. (People tend to watch anything on a screen in 
these days of multiple-tv households.) This program shows the ac- 
tual bubble sort, with, of course, a built-in display. (There is enough 
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overhead" to dispense with a timing loop.) The sort routine itself 
first resets the "swap flag" SW. If a pass is made through the list 
without SW being set, then the Hst is sorted. 

Next, the first element of the array is compared to the next. If 
A$(I) >A$(I+1), then the two elements are swapped and SW is 
set to 1. Otherwise, no swap is made. At the end of the loop, SW is 
tested. If it equals one, at least one swap was made in the pass, and 
the process is repeated once more; otherwise, the sort has been 
completed. 



100 CLS 

lia DIM A«(20) 

120 FOR 1=0 TO 19 

13B READ BS 

140 A$(I)=B* 

150 NEXT I 

155 FOR 1=0 TO 18 STEP 2 

160 GOSUB 20000 

165 NEXT I 

170 SW=0 

175 P=P+1 

IBB FOR 1=0 TO IS 

190 IF A3i<! i<=A«(l + l ) GOTO 2 

200 B*=A1^<I) 

210 A$(i:i=A*(I + l J 

220 AS(I+1)=BS 

230 SW=1 

235 GOSUB 20000 

240 NEXT I 

245 PRINT aS96,"PABS";P: 

250 IF SW=1 GOTO 170 

260 PRINT a 896, "SORT DONE" 

270 GOTO 270 

300 DATA "ELECTRON", "LA SMOG 

310 DATA »#3 BALL BEARING", 

320 DATA "BALLOON", "BALL OF 

330 DATA "PERISPHERE", "RAMA 

20000 C«=" 

20010 IF K10 PRINT 3(1*64+5 

20020 1=1+1 

20030 IF KIB PRINT 3(1*64+5 

20040 1=1-1 

20050 RETURN 



lear- screen 

-ray for data 

■'setup for data to arrar 

' read data item 

'move to array 

'corrtinue til done 

'loop for array display 

'display array 

' 1 OOP 
' ' set change f 1 ag 

'bump pass count 

'setup loop for sort 

'9o If sorted (2 items! 

' temporary storage 

'move Item up 

'move item down 

'set chpange flag 

'display change 

'continue ujith loop 

'print pass count 
' '9o again if change 
' done 

DIAMOND" , "PEA" . "MARBLE" 
FABERGE EGG" . "BASEBALL" , "ORANGE" , "BOWLING BALL" 
STRING". "747 TI RE" , "DOUGHNUT" ," GOODYEAR BLIMP" 
, "PHOBOS" , "MARS" . "EARTH" 

),A$(Ii!M;ELSE PRINT a( I-10)»64+35, A3i( I ) ; C*; 
>>AS(I)!C«;ELBE PRINT a( I-10)«64+35, A*( I ) ; Ci: 



Figure 7-8. Bubble sort. 

The worst-case time for this type of sort occurs when the list is 
ordered in reverse order. Then a swap must be made for each set 
of elements except for those not ordered at the bottom from previous 
passes. For a twenty-item list, this worst case is 19-t- 18-1-17-1- . 
+2-|-l=190 swaps and nineteen passes, quite time consuming for a 
sort! ( You may want to reorder the fist in worst-case fashion and note 
the mcreased time.) The bubble sort becomes increasingly longer as 
the list grows in size. One list twice as long as another may take ten 
or twenty times the time to sort. Clearly, what we need is a faster 
sort than the bubble sort, if we are ever going to get our mailing list 
sorted and printed out. 
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The (New) Shell Game 

One sort that is quite a bit faster than the bubble or double-buffer 
sort is the Shell-Metzner sort, named after the originator, Shell, and 
a modifier, Metzner. The Shell-Metzner sort divides up the sorting 
task into several internal sorts as shown in Figure 7-9. The 16 ele- 
ments shown in this example are divided first into eight groups ot 
two The items for each set are sorted. Next the Hst is divided into 



BEFORE FIRST 
PASS 

1' 
12 

3 
13 

5 

6 
16 

2 
11 
10—1 

4 



AFTER 
SORTl 

1—1 
10 
3 



7- 
9- 
14- 
15- 



5- 

6- 

14- 

2- 

11- 

12- 

4- 

13- 

7- 

9- 

16- 

15- 



_ 



8 LISTS 
OF 2 
ENTRIES 



4 LISTS 
OF 4 
ENTRIES 



AFTER 
SORT 2 

1 — 

6- 

3- 

2- 

5- 

9- 



7- 
10- 
14- 
13- 
11- 
12- 
16- 
15- 



^_ . 



AFTER 
SORTS 

1 — 

2 — 

3 — 

6 — 

4 — 

8 — 

5 — 

9 — 

7 — 
lo- 
ll— 
12 — 
14 — 
13- 
16- 
15- 



AFTER 
SORT 4 

1 

2 

3 

4 

5 

6 

7 

8 

9 
10 
11 
12 
13 
14 
15 
16 



2 LISTS 
OF 8 
ENTRIES 



1 LIST 
OF 16 
ENTRIES 



A SORTED 
(SIC) MESS 



Figure 7-9. Shell-Metzner sort algorithm. 



four groups of four, and these elements are sorted in a manner remi- 
niscent of the bubble sort. Then the Hst is divided into two groups 
of eight with another bubble-like sort occurring. Finally, a sort ot 
one group of 16 is performed to end the sort. The entire sort has 
been implemented in a maximum of 84-124-14+16=50 swaps in four 
passes, whereas the maximum for the bubble sort would have been 
154-144-134- . . . 4-24-1=120 swaps and 15 passes. 

The Shell-Metzner sort for our standard list is shown in Figure 
7-10. It displays in similar fashion to the bubble sort discussed ear- 
lier. The Shell-Metzner sort executes quite a bit more rapidly than 
the bubble sort even for such a small Hst, and it will operate at 
speeds hundreds of times faster for longer Hsts. 

Toward a Faster Sort 

Is the SheU-Metzner sort the ultimate sort? There are faster sorts, 
such as Hoare's Quicksort, but the Shell-Metzner is a good soHd 
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'clear scr-eert 
'arrav for data 
" 'setup for data to array 
'read data item 
'move to arrav 
*~'continue til done 
■'loop for array display 



array 



' display 
*" ' 1 OOP 

'set pass count to 
'set ^ of lists to array 

'processing 1 oc 

'90 if done 



one 



■ ' processing 
'start of a 



loop two 
Ust 



100 CLS 

110 DIH AS<20) 

120 FOR 1=0 TO 19 

13B READ B« 

140 A«<lj=BS 

150 NEXT I 

155 FOR 1=0 TO IS STEP 2 

157 J=I+1 

160 GOBUB 20000 

165 NEXT I 

166 P=0 
170 M=20 
175 M=INT(M/2> 
1B0 IF H=0 SOTO 270 
182 P=P+1 

184 PRINT 3896. "PASS=" ;P 

185 FOR ST=0 TO M-1 
170 I=ST 
195 J=ST+M 
200 SW=0 

205 IF A*(I)< =A*<J) GOTO 235 
210 SW=1 
215 B«=AS(I) 
220 A» < I ) =A* ( J > 
225 A«<J)=B5 
230 GOSUB 20000 
235 I=J 
240 J=J+M 

245 IF J<20 GOTO 205 
250 IF SW=0 GOTO 260 
255 SOTO 190 
260 NEXT ST 
265 GOTO 175 

270 PRINT a 896, "SORT DONE' 'dont that beat all 

2B0 GOTO 280 - 1 oop here for appearance 

300 DATA "ELECTRON", "LA SMOS" , "DIAMOND" .» PEA" . "MARBLE" 

310 DATA "#3 BALL BEARING" , "FABERGE ESG" , "BASEBALL" . "ORANGE" , "BOWLING BALL" 
320 DATA "BALLOON", "BALL OF STRING", "747 TIRE" , "DOUGHNUT" , "SOODYEAR BLIMP" 
330 DATA "PERISPHERE", "RAMA". "PHOBOS", "MARS", "EARTH" 
20000 C*=" 

20010 IF K10 PRINT a(I«64+5),A$(I )!CS;ELSE PRINT a( I-10)*64+35, A$! 1 ) ; Ci! 
20030 IF J<10 PRINT a(J»64+5),A«(J);C»;ELSE PRINT a< J-10X64+35, A«( J! ; C»; 
20050 RETURN 



'set change switch to 
■'if ordered, continue 

'not ordered, swap 

' temporary storage 

'move up 

'move down 

'print change 

'look for next two 

' entries 
■•go If still this list 

'So if this list sorted 

'this list still unordered 
■' go for next 1 ist 
■ for next set of lists 



Figure 7-10. Shell-Metzner sort. 

sort that is still understandable to the BASIC user (and the author) 
and can therefore be adapted to a variety of data structures. 

How about another exercise? Find faster and faster sorts until 
(in a relative way) you are able to sort your data even prior to load- 
ing it into the machine! 

Mergers Are Big Business 

We've now talked about searches and sorts. Are you ready for 
merges? (Wait! Come back!) Merges are another common opera- 
tion in data processing. A merge takes (generally) sorted data from 
one list and merges it into sorted data in a second list. Business data 
processors call this creating a new master file from an old master 
file and a transaction file. The transaction file contains the current 
data, while the old master contains the previously ordered data base. 

Merging, in the case of BASIC lists, involves obtaining a data item 
to be merged and then searching a list for the point at which the 
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data item should be inserted, as shown in Figure 7-11. The data after 
the insertion point is then moved down, and the data item is inserted 
in the "gap." The search technique can be any of the search types 
we have discussed in this chapter. 

Commonly, we would like to be able not only to search for and 
insert data, but also to delete items from hsts and modify existing 
items in Hsts. These operations have a wide variety of uses from up- 
dating inventories to maintaining directories of disk files. 

OPERATION: MERGE "MACKEREL" INTO LIST 
1. FIND INSERTION POINT 2. INSERT 



#3 BALL BEARING 




#3 BALL BEARING 




747 TIRE 




747 TIRE 




BALL OF STRING 




BALL OF STRING 




BALLOON 




BALLOON 




BASEBALL 




BASEBALL 




BOWLING BALL 




BOWLING BALL 




DIAMOND 




DIAMOND 


—REMAINS 


DOUGHNUT 




DOUGHNUT 




EARTH 




EARTH 




ELECTRON 




ELECTRON 




FABERGE EGG 




FABERGE EGG 




GOODYEAR BLIMP 




GOODYEAR BLIMP 




LA SMOG 
MARBLE 
MARS 
ORANGE 


4 


LA SMOG 




MACKEREL 


—INSERT 




MARBLE 




PEA 




MARS 




PERISPHERE 
PHOBOS 




ORANGE 
PEA 


— MOVE DOWN ONE 


RAMA 




PERISPHERE 

PHOBOS 

RAMA 











Figure 7-11. Merging algorithm. 

The deletion is the reverse of the insert, as shown in Figure 7-12. 
The item to be deleted is located by a binary or other type of search 
and then deleted by moving the remainder of the data in the list up 
over the item to delete it. The last data item is then zeroed or blanked 
to create a new "gap" at the end of the Mst. The process of moving 
data in both the insert and delete functions can be very time con- 
suming, as shown in this code that moves 200 elements of an array 
up one block to simulate a deletion. 
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OPERATION: DELETE "EARTH" FROM LIST 

1. FIND ITEM 2. DELETE 



#3 BALL BEARING 




#3 BALL BEARING 




747 TIRE 




747 TIRE 




BALL OF STRING 




BALL OF STRING 




BALLOON 




BALLOON 


— REMAINS 


BASEBALL 




BASEBALL 




BOWLING BALL 




BOWLING BALL 




DIAMOND 




DIAMOND 




DOUGHNUT 

EARTH 

ELECTRON 




DOUGHNUT 




4 


# 






ELECTRON 




FABERGE EGG 




FABERGE EGG 




GOODYEAR BLIMP 




GOODYEAR BLIMP 




LA SMOG 




LA SMOG 




MARBLE 




MARBLE 


^MOVE UP ONE 


MARS 




MARS 




ORANGE 




ORANGE 




PEA 




PEA 




PERISPHERE 




PERISPHERE 




PHOBOS 




PHOBOS 




RAMA 




RAMA 





Figure 7-12. Deletion algorithm. 



100 DIM A(2000) 

no For 1 = TO 1998 

120 A(I)=ACI + 1) 

130 NEXT I 



'establish array 
''start of loop 
'move up 
.'loop 



The above code takes about 26 seconds. If many block moves are 
to be done for merge operations, might not there be a faster vi'ay to 
maintain ordered lists? Ah yes, my friends ... I have here a little 
gem-dandy device called the . . . 



"^ ■^ 



f- 



EXCELLO 
LINKED LIST 






ik ^ 



Cures slow-speed merges, dandruff, loss of weight. . . . The price, 
you ask? . . . Well, my friend, only a little more complex data struc- 
ture. . . . 

Linked lists are worth mentioning here because they are an effi- 
cient data structure. The expense is a more complicated data struc- 
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HD 



POINTER TO 

"HEAD" OF 

LIST 





27 


12 










A(U) 


-• \ 


\ 


A(l) 


479 


-1 


A(2i 


450 


1 


A(3) 


13 







_> 
-> 


A(4) 


400 


2 


J 


A(5) 


399 


4 










> 




A(6) 


1 


3 


^ 




" 




A(7) 


195 


8 


■" N 




A(8) 


257 


9 


A(9) 


320 


10 


Anni 


365 


5 










A(1U 


111 


7 


J 


A(1?) 


65 


11 













DATA POINTER 

ITEM TO NEXT 

IN ITEM IN 

LINKED LIST 

LIST LAST = -1 



Figure 7-13. Linked-lisl structure. 

ture, together with larger storage requirements for data. A linked 
list is shown in Figure 7-13. 

The linked list is made up of data items which are linked to each 
other by pointers. Because each element points to the next, the data 
elements do not have to physically follow one another, as shown in 
the figure. What is the advantage of this? Because a link may be 
broken at any spot, a data item may easily be inserted or deleted. 
Figure 7-14 shows an insert operation, for example. The item 345 
is to be inserted in its proper place in the list. Starting from the head 
of the list, a search is made for the insertion point, which is after 
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OPERATION: INSERT 345 IN LINKED LIST 
1. FIND INSERTION POINT 



2. CHANGE POINTERS 



A(0) 


27 


12 




A(l) 


479 


-1 




A(2) 


450 


1 




A(3) 


13 







A(4) 


400 


2 




A(5) 


399 


4 






b 




A(6) 


1 


3 




A(7) 


195 


8 




A(8) 


257 


9 




A(9) 


320 


10 




Ann) 


365 


5 




J 






INSE 






A(ll) 


111 


7 


?TION 


A(12) 


65 


11 


POINT 



NEW ITEM A(13) 



345 


- 



A(0) 

A(l) 

A(2) 

A(3) 

A(4) 

A(5) 

A(6) 

A(7) 

A(8) 

A(9) 

A(10) 

A(ll) 

A(12) 

Afl3) 



27 


12 




479 


-1 




450 


1 




13 







400 


2 




399 


4 




. ) 


1 


3 


195 


8 


257 


9 


320 


13* 


365 


5 




) 










111 


7 


65 


11 






345 


10" 


J 







•CHANGED 
"ADDED 

Figure 7-14. Insertion using linked list. 

320 and before 365. The pointer at item 320 points to 365. This 
pointer is changed to point to 13 (the number of the new item), and 
the pointer associated with the new item is initialized to point to 
item 10. The new item has been inserted in the hst without moving 
a large block of data. 

Deletion of an item in a linked list is shown in Figure 7-15. Item 
257 is to be deleted from the list. Item 195 points to item 257, which 
points to item 320. Item 257 is removed by changing the pointer in 
item 195 to point to 320. The storage associated with item 257 is 
released back to a storage pool by blanking item 257 in some fashion 
such as putting in an invalid item number. 

Insertions and deletions of lioked-list items can be done very rap- 
idly once the insertion or deletion point is found. Because of the 
pointer structure, however, the search to find the iosertion or dele- 
tion point is essentially a sequential search that starts from the head 
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OPERATION: DELETE 257 IN LINKED LIST 

1. FIND ITEi TO BE DELETED 2. CHANGE POINTERS 



A{0) 


27 


12 




A(l) 


479 


-1 




A(2) 


450 
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A(3) 


13 







A(4) 


400 
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8 
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10 
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27 


12 




A(l) 


479 
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A(2) 


450 
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A(3) 


13 







A(4) 


400 
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A(5) 


399 


4 
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A(6) 


1 


3 


A(7) 


195 


9* 


N 




A(8) 


::::;::::::::*"**V|:;:S;: 


* + t + 


A(9) 


320 


10 


.« > 

J 


A(in\ 


365 


5 






A(ll) 


111 


7 




A(12) 


65 


11 





♦CHANGED 
"**MARKED AS "UNUSED' 



Figure 7-15. Deletion using linked list. 

of the list; like all sequential searches, it is rather time consuming. 

Let's take a look at a practical example of the linked Ust concept 
in BASIC. Figure 7-16 shows a linked-list structure for a list of alpha- 
betic data, our standard Chapter 7 list of odds and ends. The struc- 
ture has two arrays. Array A contains the pointers, while array A$ 
contains the items of the Hst. The pointers are actually the indices 
to the elements of array A$. The last pointer is a -1 to signify that 
there are no more items in the Hnked list. 

Initially, the items in the linked list are ordered by initializing 
the pointer array as shown in Figure 7-16. In this case, the items 
are ordered physically as well as ordered in the linked Hst. 
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12 


12 


13 


13 


14 


14 


15 


15 


16 


16 


17 


17 


18 


18 


19 


19 


-1 




20 ! 


-2 1 
UNUSED 1 




29 1 

L 


-2 1 





A$(0) 


#3 BALL BEARING 


1 


747 TIRE 


2 


BALL OF STRING 


3 


BALLOON 


4 


BASEBALL 


5 


BOWLING BALL 


6 


DIAMOND 


7 


DOUGHNUT 


8 


EARTH 


9 


ELECTRON 


10 


FABERGE EGG 


11 


GOODYEAR BLIMP 


12 


LA SMOG 


13 


MARBLE 


14 


MARS 


15 


ORANGE 


16 


PEA 


17 


PERISPHERE 


18 


PHOBOS 


19 


RAMA 


20 ] 
29 i 

1. 


UNUSED 1 



Figure 7-16. Example of linked list. 
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100 CLS 

110 CLEAR 1000 

120 DIM A(29) 

130 DIH A!6(29) 

1A0 FOR 1=0 TO IB 

150 A<I)=I+1 

160 READ B$ 

170 A«<I)=B$ 

180 NEXT I 

190 A(l'5)=-1 

195 REAP B« 

200 A»(I)=BS 

210 FOR 1=20 TO 29 

220 A(I)=-2 

230 At( I )="*«»*" 

240 NEXT I 

250 HD=0 

400 CLS 

410 PRINT "HD=";HD 

420 FOR 1=0 TO 29 

430 PRINT TAB(5) !I.A(I).A$(I) 

440 FOR J=0 TO 10 

450 NEXT J 

460 NEXT I 

500 INPUT "DELETE (D) OR INSERT (I)";B 

510 IF BS<>"D" AND BSO"!" SOTO 500 

520 IF B$="D" GOTO 2000 

1000 FOR ZC=0 TO 29 

1010 IF A(ZC)=-2 GOTO 1050 

1020 NEXT ZC 

1030 PRINT "NO FREE ITEMS" 

1040 GOTO 500 

1050 INPUT "STRING TO INSERT" ;B« 

1060 A*(ZC)=B« 

1070 IF HDO-1 SOTO 1110 

1080 HD=ZC 

1090 A(ZC)=-1 

1100 GOTO 400 

1110 ZL=HD 

1120 ZN=A(ZLS 

1130 IF ZNO-1 SOTO 1170 

1140 A(ZL)=ZC 

1150 A(ZC)=~1 

1160 GOTO 400 

1170 IF B3i>=A*(ZL) AND B$<AS(ZN) GOTO 

1180 ZL=ZN 

1190 ZN=A<ZN) 

1200 GOTO 1130 

1210 A<ZL)=ZC 

1220 A(ZC)=ZN 

1230 GOTO 400 

2000 IF HDO-1 GOTO 2030 

2010 PRINT "STRING NOT FOUND" 

2020 GOTO 500 

2030 INPUT "STRING TO DELETE" ;BS 

2040 ZL=-1 

2050 ZC=HD 

2060 ZN=A(ZC) 

2070 IF A3i(ZC)=B» GOTO 2120 

20B0 IF A(ZC)=-1 GOTO 2010 

2090 2L=ZC 

2100 ZC=A(ZC) 

2110 GOTO 2060 

2120 IF ZL=-1 HD=ZN ELSE A(ZLi=ZN 

2130 A(ZC)=-2 

2135 A3i<ZC)="»*»»" 

2140 GOTO 400 

3000 DATA "#3 BALL BEARING" . "747 TIRE 



r~ ' 1 oo 

|_.9C. 



cl ear- screen 

clear string storage 

pointer array 

itetii array 

loop for first i^ 
setup pntrs 
read from data 1 ist 
and store m array 
loop til done 
' 1 ast pntr = -1 
'get last data item 
'and put in array 

t' 1 OOP for unused entries 
'mark pntr unused 
'mark item unused for disF 
' 1 OOP 

'set head to first item 
■* cl ear screen 
'head title 
— 'loop for items 
' pr-int 1 terns 

C' timing for disp 
' loop 
' 1 OOP for print 
— ' prompt user 
test response 
delete 
loop for unused item 
if unused 
unused found yet 
' no free items 
'back to command mode 
'input insert string 
'fill into array 
'go if items in 1 ist 
'head now current 
'current now last 
'back to command 
' 1 ast item 
'next item 

'90 if n C' t end of list 
' change pointer 
' new end of 1 i st 
' back for new command 
' c hie c k for- in se r- 1 po i n t 
'not f nd~cont inue 
' new next 
' keep 1 ooking 
' found-change pntr 
' current to next 
'back for next command 
'delete here-go if items 
' rio items in 1 ist 
'back to command 
'jnrut delete string 
"initialize last 
' initial ize current 
' next 

'go if found 
'go if end of list 
'not this entry 
' get next 



3005 DATA 
:-?0l0 DATA 
3020 DATA 

3030 DATA 



' keep searching 
' found-change pntrs 
' mark unused 
'mark entry for display 
'back to command input 
BALL OF STRING" 

BALLOON" , "BASEBALL ■* ^ "BOWLING BALL" , "DIAMOND" 

DOUGHNUT" , "EARTH" ■ "ELECTRON" . "FABERGE EGG" . "GOODYEAR BLIMP" 

LA SMOG" ^ "MARBLE" i "MARS" . "ORANGE" . "PEA" . "PERISPHERE" 

PHOBOS"'* "RAMA" 



Figure 7-17. Linked-list code. 
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The code shown in Figure 7-17 allows us to delete or insert items 
in the linked list. The contents of the list are displayed on the screen 
in the form 



POINTER I ITEM [ 

so that you can see what is actually happening in the insertions and 
deletions. Each deletion is handled by searching the A$ array by 
using the pointers, starting with HD, a variable which points to the 
first item of the linked list. When the item to be deleted is found, 
the previous pointer is changed to the pointer value for the deleted 
item, and the pointer element in A is marked as unused by setting 
it to -2. Each insertion finds an unused position by searching the A 
array for -2 and then searches the A$ array for the insertion point. 
When it is found, the previous pointer is changed to the new loca- 
tion, and the pointer for the new location is changed to the value 
found in the previous location. 

Naturally, we have provisions for deleting all items in the Hst 
and for overflow of the size of the arrays. (A favorite trick for com- 
puter science students is trying to "crash" the time-sharing system; 
it's human nature to look for loopholes, but we must warn you that 
all programs in this book are perfect and that any such attempts will 
result in confiscation of your TRS-80 monitor! ) 

That completes our discussion of data structures, sorting, search- 
ing, and merging. We hope that this chapter will provide some alter- 
natives in the way you arrange your data and maintain it in orderly 
fashion. There is no optimum data arrangement or sorting technique 
that will work for all cases. The "correct" techniques must be related 
to the type, size, and speed requirements of the program and data 
involved. 
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CHAPTER B 



The TtS-80 Functions Perfectly 



In this chapter, we'll cover the built-in TRS-80 functions. Func- 
tions are "built-in" operations to process specific things, rather than 
general-purpose statements. Naturally, the specific things that the 
functions process are commonly used operations, such as finding the 
sine of an angle or generating a random number. Functions in Level 
II BASIC can be divided into four different types-precision func- 
tions, numeric functions, random-number functions, and trigonomet- 
ric functions. We'll discuss all four and the applications of each. 

What? More Precision Operations? 

We know, we covered precision in Chapter 2. The statements in 
Chapter 2, however, defined a variable as an integer, single-preci- 
sion, or double-precision variable. The variables defined by the pre- 
cision statements and suffixes remained that precision for the entire 
program. The two functions presented here, CDBL and CSNG, allow 
the user to force a double-precision or single-precision operation 
without having to define the variables as double or single precision. 
CSNG forces a single-precision result. If, for instance, we have two 
double-precision variables, A# and B#, the results of any operations 
would normally be carried out to 17 digits as in the code 



100 CLB claar- screen 

200 INPUT »A#="!A# 



300 INPUT "B«="!Btt 

ABB PRINT "Att«B»=" !A#»B« 

500 GOTO 200 



input 1st dp value 
input 2nd dp value 
print product 
^'go for next set 



Inputting A# = 1.22222222222222 and B# = 2.33333333333333 
would result in an answer of 2.851851851851843. However, if we 
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forced the answer to single precision, using the CSNG function, the 
answer would be 2.85185, a single-precision number. 



1000 CLS 

1100 INPUT ■A#=";A# 

1200 INPUT "B)t=";B# 

1300 PRINT ■A#«B«=" ;CSNS(A«*ett) 

1400 GOTO 1100 



clear screen 
1 nput 1st dp val ue 
input '2nd dp value 
print product sp 
Q':- for ne::;t set 



The CSNG function is a means of limiting results to single-preci- 
sion accuracy without having to introduce a single-precision variable 



as m 



2000 


CLS 


'clear screen 


2100 


INPUT "AS=";A» 


-'input 1st dp value 


2200 


INPUT "B#=»!B4t 


' input 2nd dp value 


2300 


C=A#*B# 


'convert product to 


2400 


PRINT "A#*B#=";C 


'print SP product 


2300 


GOTO 2100 


'90 for next set 



which would give the same result as the CSNG function above. 
When the CSNG function converts a double-precision function to 
single precision, it rounds off, rather than truncating, the least sig- 
nificant digits. 

The CDBL function operates in similar fashion to CSNG, except 
that it forces a double-precision operation. CDBL performs the same 
operation as the generation of the double-precision value C# from 
AandB 



3000 CLS 

3100 INPUT "A=" ;A 

3200 INPUT "B="iB 

3300 C#=A»B 

3400 PRINT "C#="!C#, 

3500 SOTO 3100 



' ' input 1st 



CDBL ! A*B ) =" ; CDBL < A*B ) 



r input 1st SP number 
'input 2nd SP nunffc.er 
'convert to dp 



-for next set 



Converting to the double-precision format, by the way, cannot 
"restore" accuracy to a number. If operations have been performed 
in single precision in a program, then only seven digits of precision 
are maintained (six are printed). Double-precision format must be 
used continuously to guarantee 17 digits of accuracy! 

Converting from single to double precision also has its pitfalls. 
Converting the single-precision number 1.999995 should result in 
1.9999950000000000, shouldn't it? In fact, converting this number, 
as in 

100 PRINT CDBL(1. 999995) 

results in "1.999994874000549"! Similar conversions also produce 
extraneous digits at the end. 

A better method of converting from single to double precision is 
to use the approach 
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100 A#=VAl(STR$(AI)) 

which converts the single-precision value of A! into a string value 
and then converts the string into a double-precision numeric value. 
(See Chapter 3 for a discussion of STR$ and VAL.) When this 
method is used with 1.999995, a "rounded-off' value of "2" results 
without extraneous digits. We'll say more about truncation and 
roundoff shortly. 

Are You Good at Fractions? 

There are several numerical functions in Level II BASIC that 
help us in deahng with integers. They are CINT, INT, and FIX. 

CINT returns an integer value in the range -32768 through 
+32767. This is a comparable function to the CSNG and CDBL 
functions we have just discussed. The CINT function is equivalent 
to creating an integer value such as A% rather than forcing a con- 
version to integer form with a function. 



100 CLS 'clear screen 

2B0 INPUT "A=";A [-'input Ist sp number 

300 INPUT "B=";B 'input 2nd sp number 

400 cy.=A*8 I 'find integer- value 

500 PRINT "C-/.=":C-/.. "CINT<A*B) = "!CINT(A»B> 

600 SOTO 200 "-'go for next set 



Because of the way negative numbers are held in two's comple- 
ment form (see Chapter 2) and the truncation method of conversion, 
CINT converts a negative fractional number to the next lowest in- 
teger value. CINT will convert the following values as shown 

Before After 

CINT CINT 

-1.1 -2 

-1.9 -2 

-12.001 -'3 

-32767.1 -32768 

Positive fractions are converted to the integer portion of the number. 
The fractional part is truncated, or chopped off. 

Before After 

CINT C'NT 



1.1 
1.9 



12.001 '2 

32767.1 32767 

CINT is very similar to another integer function, "INT." CINT is 
a high-speed version of the more general INT. INT will work with 
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numbers greater than +32767 and less than -32768. Because INT 
is more general, it is almost always used in BASIC programming in 
preference to CINT. 

CINT is commonly used in operations to find the remainders of 
numbers. This type of operation comes up frequently in number 
conversions and rounding operations. Decimal numbers can be con- 
verted to binary or hexadecimal numbers by a common method 
known as "divide and save remainders." It's a good application to 
show the use of CINT. 

Before we look at the code, let's see the "pencil and paper" oper- 
ation. Suppose we have a decimal ninnber that we want to convert 
to binary. We start by dividing by 2 and save the remainder at each 
division, as shown in Figure 8-1. The remainders in reverse order 
are the binary-number equivalent of the decimal number we started 
with. This method works for any number base— binary, octal (8), or 
hexadecimal (16). 



Rl 1 






2tl RO 




2l2 Rl 




2 15 Rl t 


2 1 11 RO 


[ 11 1 = 353 


2 1 22 RO 


, 


1 


2 1 44 RO 






2 1 88 RO 












L 1 1/b Kl 






2 1353 




Figure 8-1. Decim 


al-to-binary con 


version. 



For those of you interested in assembly-language coding and for 
anyone interested in binary representation, we present the following 
subroutine to convert any given decimal number from to 255 into 
binary form. The number is in variable ZN, and the result is put in 
array ZZ defined by a previous DIM ZZ(7). 



100B0 FOR ZI=7 TO STEP -1 
10010 ZZ(ZI)=ZN-INT(ZN/2>«2 
10020 ZN=INT(ZN/2) 
10030 NEXT ZI 
10040 RETURN 



- 'setup B time Icop 
find remainder 
find quotient 
"" ' continue 
'return to calling pr-oQ 



The subroutine does not check for a number outside the proper 
range of through 255. If a number greater than 255 is to be con- 
verted, you'll get an incorrect answer. ( Eight divisions will only re- 
solve numbers that are 255 or less. You might like to try 16 divisions 
with a 16-element array for use vdth numbers of 65535 or less. ) The 
number to be converted is in variable ZN. A one-dimensional array. 
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ZZ, must have been defined previously. (Defining it in the subrou- 
tine would result in a DD error for subsequent calls.) For eight 
iterations through the loop, the number is divided by two to give 
some quotient. This quotient will probably be a fractional number. 
To find the integer portion of the quotient, INT is used. INT(ZN/2) 
will give the integer quotient value. If this quotient is multiplied 
by 2, and the result subtracted from the original number, we can find 
the remainder. The remainder is calculated this way and stored in 
the array in reverse order. An example might make this more lucid 
( I'm even confused at this point ) . 

Suppose we want to convert 213 to binary form. If we did it vsith 
paper and pencil, we would have the calculation shown in Fig- 
ure 8-2. 



11 1 1 1 = 213 






Rl 


2 nr 


Rl 


2 rr 


RO 


2rr 


Rl 


2rTr 


RO 


2 126 


Rl 


2 153 


RO 


2 1106 


Rl 


2 1213 





Figure 8-2. Example of decimal-to-binary conversion. 

When we do the same conversion using the subroutine, we get 
the calculations shown in Figure 8-3. 

We can use the subroutine above to practice our binary opera- 
tions (don't forget those ands and ors) or to PEEK at memory lo- 

iNT(ZN/2)*2 ZN-!NT(ZN;2)»2 
I ZN ZN/2 INT(ZN;2) (ZN) (ZZ) 



7 


213 


106.5 


6 


106 


53 


5 


53 


26.5 


4 


26 


13 


3 


13 


6.5 


2 


6 


3 


1 


3 


1.5 





1 


0.5 

Rl 

2 IT Rl 

2 ITRO 

2 IT Rl 

2 1 13 RO 

2 1 26 Rl 

2 1 53 RO 

2 1 106 Rl 

2 1213 



106 


212 


>~l 


53 


106 





26 


52 


1 


13 


26 





6 


12 


1 


3 


6 





1 


2 


1 



















Figure 8-3. Decimal-to-binary conversion algorithm. 
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cations for assembly-language work. To convert any number from 
to 255, use the following code. 

1000 DIM ZZ(7) 'allocate B dim array 

U00 PRINT r'neu, line 

12B0 INPUT "DECIMAL *l TO BE CONVERTED" ! ZN 

1300 IF ZN>255 OR ZN<0 SOTO 1200 

1400 GOSUE 10000 

15B0 PRINT "BINARY ESUIV IS "! 

1600 FOR 1=0 TO 7 

1700 PRINT ZZ(I j ! 

1B00 NEXT 

1900 SOTO 1100 



'check for range 0-255 

' conver-t 

' print resul t msg 

digits 
iigit 



C' 1 OOP for 
'print di? 
' continue 



'go for next number 

To convert a given range of ROM or RAM memory locations, use 
this code. 

2000 DIM ZZ<71 'allocate B dim array 

2100 INPUT "START LOCATION" ;A 'input starting location 

2200 INPUT "END LOCATION" ;B 'input ending location 

2300 FOR I=A TO B 

2400 ZN=PEEK(I) 

2500 SOSUB 10000 

2600 PRINT "LOCATION=" ; I !"CONTENTS=" : 

2700 FOR J=B TO 7 

2B00 PRINT ZZ(J) ! 

2900 NEXT J 

3000 PRINT 

3100 NEXT I 

3200 END 



'outer loop for locns 
'get next locatioff 
' convert bvte 
' 1 ocat ion msg 

inner loop for digits 
print digits 
continue for 8 
neiu 1 ine 
get next location 



r; 



A second use of INT is to test whether a number is divisible by 
another number. Many times, it's convenient to test whether this is 
the seventh or tenth time through a loop, for example. If we are 
displaying 16 lines of characters on the video display, we can pause 
while the user scans the current page by keeping a count of the 
number of lines and testing for multiples of 16. This code is not a 
working program, but illustrates how the test may be integrated 
in a program. A$ represents the ENTER response to the pause at 
the 16th Une. GOTO 800 is the branch to "other" processing. 

100B PRINT A,B 

1010 CT=CT+1 

1020 IF INT(CT/16)=CT/16 THEN INPUT A* 

1030 SOTO 800 

Another use of INT is to test whether a number is an integer value 
(not a fraction). A convenient way to do this uses INT: 

1B0 INPUT A r-'inp..c test number 

200 IF INT(A)=A PRINT "A IS INTEGER" ELSE PRINT "A NOT INTEGER" 

300 SOTO 100 I- 'continue for next 

The fractional portion of any positive number can be found by 

100 FR=A-iNT(A) 

Since INT converts to the next lowest negative integer for negative 
numbers, A-INT(A) wall not give the correct result for A < 0. 
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However, still another function, FIX, will give the fractional por- 
tion of a negative number or positive number correctly. 
FIX truncates all fractional digits. Some examples are 

Bafore AHar 
FIX FIX 

1.2 1 

13.1 13 

13.99 13 

128.123 128 

-1.1 -1 

-3.3 -3 

-128.99 -128 

-99999.9 -99999 

Why are there so many ways to derive similar things? What is 
truth? What is beauty? Some of the functions described above are 
very similar, and it's hard to know when to use one or the other, 
but please don't complain— the alternative might be a BASIC 
stripped of all these niceties. It's better to have too much than too 
little (Guard— take down the name of that reader threatening to 
go hack to his hand calculator!). 

A word should be said here about truncation and roundoff. We 
have seen how INT and FIX truncate values. For small numbers 
such as 1.9 or 2.7, the error resulting from truncation is quite large. 
A roundoff scheme may be used to reduce this error for individual 
numbers. In roundoff, we make some arbitrary judgment as to 
whether the number should be rounded "up" to the next larger 
integer or rounded "down" to the next smaller integer. (This scheme 
can also be used for fractional numbers. ) The following code rounds 
up if the fraction is 0.5 or greater and rounds down if the fraction 
is less than 0.5. 

100 INPUT A ["'input test number 

200 B=FIX(A) I 'truncate fraction 

300 IF ABS(A-B)> = .5 B=B + 1 

400 PRINT A,B | 'print input and result 

500 GOTO 100 L 'continue for next 



A Sign Function — Absolutely! 

The SGN function is used to test for a negative, zero, or positive 
result. Here again, we could do this by other means such as 

100 IF A<0 GOTO 1000 ELSE IF A=0 GOTO 2000 ELSE GOTO 3000 

The SGN function makes the job somewhat easier, however, 

100 ON SGN(A) + 2 GOTO 1000,2000,3000 

The SGN returns -1 if the argument is less than 0, if the number 
is equal to 0, and 1 if the argument is greater than 0. In the state- 
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ment above, the result of -1, 0, or 1 is converted to 1, 2, or 3 by the 
SGN(A) + 2 to cause a "computed" GOTO, transferring control 
to 1000 for negative numbers, 2000 for numbers equal to 0, and 
3000 for positive numbers. 

Another simple-minded function is the absolute value. {Sorry, we 
didn't mean to shun the absolute value— we mean it's easy to under- 
stand. ) The absolute value, as we know from Algebra One, returns 
A if A is positive or zero, and returns -A if A is negative. All this 
says is that the magnitude of the number is returned. A = ABS( -32) 
returns 32 for A, A = ABS(+32) returns 32 for A, and A = ABS(O) 
returns for 0. A zero value, by the way, is treated as a positive num- 
ber in the TRS-80 hardware and software (and in virtually all other 
computing systems). The absolute value function is used extensively 
in many mathematical calculations, as, for example, to find the dis- 
placement along the X axis for two points on a graph 

100 DX=ABS{X2-X1) 

Another mathematical function that is built into Level II BASIC 
is the square root function, SQR. We know that we can find the 
power of any number by using the exponentiation operator t. SQR 
simply duplicates the exponentiation function for A t .5 and is some- 
what faster. Of course, square roots are common operations in mathe- 
matical routines, and it's convenient to have a built-in SQR function. 

We won't say much more about the EXP and LOG functions ex- 
cept that EXP(A) is the exponential function e^ and that LOG(A) 
returns the natural logarithm of A. Natural logarithms are used ex- 
tensively in higher mathematics. 

Pick a Number, Any Number 

Chances are the number you pick won't be a random number, es- 
pecially if you keep selecting numbers for some time. The computer 
can be used (and has been used) for a number of years for simu- 
lation of various real-world events. One of the powerful uses a 
computer can be put to is to produce "pseudo-random" numbers 
for use in simulations. 

What are pseudo-random numbers and how do they differ from 
random numbers? Truly random numbers can be produced by flip- 
ping a coin. We cannot predict whether the next flip will be heads 
or tails (assuming the coin is perfectly balanced and we are not 
introducing any "tricks" in the flip). If we recorded the heads and 
tails and equated them to ones and zeroes, we would have a long 
list of binary numbers which could be broken up into bytes (see 
Figure 8-4). The bytes would now represent a list of 8-bit binary 
numbers ranging in value from through 255. The distribution of 

149 



HEADS = 1 
TAILS = 



10011100011110001100100 100 110011. 

/ f \ \ 

10 1110 0, 01111000, 1 1 1 1, 1 1 1 1, . 



156, 120, 201, 51 

Figure 8-4. Random binary numbers. 

the numbers would tend to be uniform the longer the list was made. 
That is, if we had millions of numbers, the number of values 
would be about 1/256 of the total number, the number of 1 values 
about 1/256 of the total, and so forth. 

The problem of generating random numbers is not a trivial one, 
and many articles ( and books ) have been written about the subject. 
As a matter of fact, there are books of random numbers, used as hsts 
of good random numbers without bias. It's not only important to 
have unpredictability in Las Vegas, but in computer simulation as 
well. We can generate random numbers in the TRS-80 by manual 
methods. If we increment a count fast enough and then stop the 
count, we have a fairly random number. The following routine does 
this by examining the shift key and stopping the count when it is 
pressed. A count of to 127 is generated. (The USR call here is 
intended only for Level II and not Disk BASIC.) 



100 A»=CHR$(5S)+CHRS(12B)+CHR$<56)+CHR!f(lS3)+CHR*<40)+CHR»<250)+CHR*(237)+ 

CHR«<95)+CHRai(ni)+CHR$(3S)+CHR*(0)+CHR$<195)+CHR3i(lS4)+CHR»(lB) 
500 B=VARPTR<A3il ' 9et block location 

600 POKE li526iPEEK(B+l) 'setup usr- call 

700 POKE 1 6527. PEEK (B+2) 'second bvte of address 

800 A=USR(0) 



900 PRINT A 

1000 FOR 1=0 TO 50 

1100 NEXT I 

1200 SOTO 800 



'call machine language 
'print value 

p'delar for bounce 

'— ' loop 
'go for next value 



The "R" register in the CPU Z-80 microprocessor is continually 
being updated by adding one. An instantaneous value from R will 
be 0-127. (The character string at A$ constitutes an assembly-lan- 
guage routine embedded in a "dummy string." We'll discuss this 
technique in a later chapter. ) 



150 



Isn't there a more convenient method to generate random num- 
bers? I'm glad you asked, son. Step over here and let me shovs' you 
this little gadget called the RND number generator. . . . 

RND does not generate random numbers, but pseudo-random 
numbers. Pseudo-random numbers are predictable in that if one 
starts with the same seed number, the same sequence of numbers 
vs^ill be generated each time. The numbers generated still have a 
good distribution of values. Generating numbers from to 255 would 
result in about l/256th of numbers equal to 0, l/256th equal to 1, 
and so forth, if done over long periods of time. The fact that the 
series is predictable is not necessarily bad. We would like to be 
able to repeat experiments and simulations from the same point, 
after all, and working with truly random numbers does not provide 
that capability. 

Let's look at a sequence of random numbers generated by the 
RND function. The code below prints random numbers from 1 to 
255. The format of the RND function is RND(A). If A is 0, a single- 
precision value between and 1 is generated. If A is 1 to 32767, a 
pseudo-random value between 1 and the argument is printed. In 
this case, the argument is 255 to generate a value from 1 to 255. 

100 CLS 

200 PRINT RND(255);" "; 

300 GOTO 200 

Did you see any repeats? (Well, it is somewhat fast.) The RAN- 
DOM function reseeds the random-number generator. If RANDOM 
is not used, then turning off the computer, turning it on, and exe- 
cuting 

100 PRINT RND{10000) 'or other range 

will produce the same number for each power-up. RANDOM en- 
sures that a new sequence will be started more than 99 times out of 
100. Power down again, power up, and execute 

100 RANDOM 'randomize 

200 PRINT RNDdOOOO) 'print starting number 

several times. You will see different starting values essentially gen- 
erated by the same process of taking a count from a register as we 
performed with our random program. 

What is the provision for starting over from the same seed? Since 
we cannot specify a starting seed value in RANDOM, we must do 
some POKEing in memory. If we have a seed from through 65535 
in variable SD, we can reinitialize the seed by 
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100 FOR J=l TO 5 

200 SD=1234S 

300 POKE 16554.0 

400 POKE 16556. 1NT<SD/2S6) 

500 POKE 16555iSD-INT(BD/256)«256 

600 FOR 1=1 TO 8 

700 PRINT RND< 10000)' 

800 NEXT I 

900 PRINT 

1000 NEXT J 

1100 GOTO 1100 



setup for 5 lines 
' seed 

'0 to first seed bvte 
'ms bvte to third seed bvte 
'Is bvte to second seed bvte 
'setup for 8 values 
'random « from 1-10000 
get ne?<t number 
' skxp 1 1 ne 
- 'get next set of 8 
loop for comparison 



c: 



The seed for any random generation is contained in the three 
bytes of 16554 through 16556. We have arbitrarily zeroed the first 
byte and put the value of SD into the next tvi^o. Any scheme such 
as this could be used as long as the three bytes are always initialized 
to the same value for the start of each new pseudo-random number 
cycle. 

RND can be used as a simulation tool for any number of real- 
world events. Suppose, for example, that we want to simulate a 
dice roll. Each die has a face value of one through six, and there 
are two dice. We can easily simulate the roll of each die by using 
RND(6), which will generate pseudo-random values of 1 through 6. 



2000 


CLS 








c 


lean screen 


2100 


R=0 








total *) of rol 1 s 


2200 


DIM N0( 12) 








setup arrar for totals 


2300 


FOR 1=0 TO 50 






" 




~ ' rol 1 the dice 


2400 


PRINT a530.RND<6) 










'get value of 1-6 


2500 


PRINT a550.RND(6) 










'get value f 1-6 


2600 


NEXT I 








'keep on rolling 


2700 


R=R+! 








bump # of rol 1 s 


2800 


A=PEEK( 15360+531) 


-4B 






'get current die value 


2900 


B=PEEK( 15360+551)- 


-48 






from screen positions 


3000 


N0(A+B)=N0<A+B)+1 








' increment total for point 


3100 


PRINT a 850. "tota 


# 


of rol 1 s=" ;F 






3200 


PRINT a 908, " 2 


3 


4 5 6 7 


8 


9 10 11 12" 


3300 


PRINT 3972, "": 










3400 


FOR 1=2 TO 12 










-loop tor totals 


3500 


PRINT USING '■««#" 


;NO(I) ! 






'print totals 


3600 


NEXT 










' loop 


3700 


FOR 1=0 TO 50 










'pause before next roll 


3800 


NEXT I 








^' 1 OOP 


3900 


SOTO 2300 








'^ 


30 to roll again 



The program continuously rolls the dice and prints out the totals 
for each of the points 2 through 12. Let the program run for a while 
to see how the totals compare to the odds of "making" 2 through 12. 
The odds are given below in percentage of times a point will 
come up. 



PolnJ 

2 2.8% 
5.6% 
8.3% 
11.1% 
13.9% 
16.7% 
13.9% 



Point 

9 11.1% 

10 8.3% 

1 1 5.6% 

12 2.8% 
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Another example of how RND may be used is in a simulation of 
a fortune teller. In the program below, YES/NO questions are an- 
swered by the MYSTIFYING ORACLE program. RND is used to 
generate a value of 1 through 10. This value is then used to obtain 
one of ten strings from string array A$ to answer the question. This 
concept can be used in many similar cases to obtain random answers, 
events, or conditions. 



140 
150 
160 
170 
1B0 
190 
200 
210 
220 
230 
240 
250 
260 
270 
2S0 
290 



DIM A3.<10) ■«. + ri 

A«(l.i="NO" 

A* (2)=" YES" 

A$<3)="MAYBE" 

A* (4)=" YOU SOTTA BE KIDDING" 

Alt (5)=" PLEASE REPHRASE" 

POSSIBLY" 

EXCUSE HE. I HAVE ANOTHER CALL " 

NOPE" 

NEGATORY, GOOD BUDDY" 
WHY NOT" 

' cl ear 



A*i6) 

AS ( 7 ) = 

A$<8)= 

A$(9)= 

A3i(10) = "SURE 

CLS 

PRINT "MYSTIFYING ORACLE" 'title 

INPUT "YES"; A* f- ■ input 

PRINT A$(RND(10) )5" - NEXT QUESTION" 

GOTO 270 l_.,-,.,„^j 



I sage 
E; s 1 1 o n 





SINE=i 
c 



Figure 8-5. Sine function. 
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The distribution of answers in this program will be spread quite 
evenly among A$( 1 ) through A$( 10) if a very large number of cases 
are tried. If we want to "load" the program to bias it toward certain 
responses, the same response could be used as many times as de- 
sired. 

Another technique used quite often in game programs is to gen- 
erate that "random" catastrophic effect-the plague that strikes dur- 
ing Hammurabi or the loss of photo torpedoes during Space War. 
This can be accomplished "n times out of 100" by using a code 
such as 

1000 IF RND(100) = 100 THEN .... 

or 

1000 IF RND(100)>96 THEN .... 

The first example would be true one time out of 100 when RND 
(100) =100, and the second example would be true four times out 
of 100 when RND(100)=97, 98, 99, or 100. 



"^UITE FRANKLV, 
I'M A LITTLE 
\A/ORRIED ABOUT 



THIS NEXT CLASS, 




a 



1S4 



SINE OF 135 
0.7071 



SINE OF 45° 
7071 




SINE OF 
-0. 



Figure 8-6. Sine function through 360°. 

Trigonometric ( Say What? ) Functions 

The last group of functions we'll talk about are the trigonometric 
functions, pronounced "Trig-oh-no-mef-ric" if you are a purist. The 
trigonometric functions, as you might guess, are those arch enemies 
of high school and college students— sines, cosines, and tangents. 

We'll present a short review here, but feel free to peruse other 
material, too, if you feel you need a better understanding of these 
mathematical functions. (If you don't feel that ambitious, just stick 
around here. ) 

For any right triangle (a triangle with one right angle), the ratio 
of the opposite side over the hypotenuse is called the sine, as shown 
in Figure 8-5. Opposite to what? To a large eye that we've included 
in the figure. When this angle is very small, the ratio a/c is very 
small. If side c is kept at a constant size, as the angle increases, side 
a increases in size. Close to 90 degrees, the sides are about equal, 
and at 90 degrees, the sides are equal. 

If we continue through 90 degrees to 180 degrees, the ratio of 
side a to c decreases dovm to again. We can carry this through 
360 degrees, as shown in Figure 8-6. Notice that for angles greater 
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+1- 




Figure 8-7. Plotted sine function. 

than 180 degrees, tibe sine is negative. This is true if we assume that 
the triangles are constructed on an x-y graph with the points lo- 
cated by standard x-y "rectangular" coordinates. 

If we now graph the sine values for various angles from through 
360 degrees, we get the plot shown in Figure 8-7. The value of the 
sine increases from to 1 from to 90 degrees, decreases from 1 to 
from 90 to 180 degrees, decreases to ~1 from 180 to 270 degrees, 
and increases from -1 to from 270 to 360 degrees. 

CIRCDIVIFERENCE = 2irR 




Figure 8-8. Radian measure. 
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The sine function, expressed by the graph, is used extensively in 
mathematics and physics. Many physical events operate on a peri- 
odic basis that follows the sine function. 

Does everyone know the formula for the circumference of a cir- 
cle? (Let's see, I have it here somewhere. . . .) It's 2 times pi times 
the radius of the circle, as shown in Figure 8-8. The circumference 
of a circle with radius of three feet is 2 * 3.14159 * 3, or 18.8496. 
Because the circumference is 277T, a convenient unit known as a 
radian was invented. A radian represents an angle of 360/27r, or 
about 57.296 degrees. It's the angle represented by laying the radius 
of a circle along the circumference as shown in the figure. 

Trigonometric functions are often expressed in terms of radians 
because they easily express critical angles around the circle, such as 
45 (-77/4 radians), 90 (it 1 2 radians), 180 (tt radians), 270 (37J-/4 ra- 
dians), and 360 degrees {Itt radians). If you would rather not worry 
about radians, simply divide the angle you're using by 57.29578 to 
convert from degrees to radians and forget about any mystery in- 
volved. 

Let's display various values for the sine function from to 360 
degrees. 



100 CLS 

200 FOR 1=1 TO 360 p 'avoid /0 error 

•??? SET_<(1/360)*127, (2A-23*(SIN(1/57.2957B) ) l i 

^'continue for- 360 degree 
Moop here for display 



400 NEXT I 
500 SOTO 500 



■clear that screen 



DEGREES 45 DEGREES 90 DEGREES 



b = c 



COSINE = - 
c 



mma^mmL 



a c a 

b = 




0° 90° 180° 270° 360° 

Figure 8-9. Cosine function. 
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TAN =• 




CLOSE TO 
DEGREES 45 DEGREES 70 DEGREES 90 DEGREES 



_.Z]' 'h' '\ 



h -3 = h 

b b 



b (very small) 




Figure 8-10. Tangent function. 

This plot uses the TRS-80 x coordinates from to 127 and the 
y coordinates from 1 to 23 to avoid problems with goiag over the 
y=0 and x=127 boundaries. (We could also have expHcitly checked 
for y<0 or x>=128.) The plot shows the sine values from 1 to 360 
degrees (0 to 27r radians) with the top of the screen representing 1 
and the bottom representing -1, identical to the plot shown in 

Figure 8-7. 

The cosine function is similar to the sine function. It expresses 
the ratio of side h divided by side c. As we can see from Figure 8-9, 
the cosine graph starts off at 1 for an angle of degrees, goes to 
for an angle of 90 degrees, goes to -1 for 180 degrees, goes to for 
270 degrees, and returns to 1 for 360 degrees. The cosine function 
also figures in a great many physical and mathematical relationships. 
The format of the cosine function is identical to SIN, with the argu- 
ment in radians. 

The tangent function is the third common trigonometric function 
represented in the TRS-80. It expresses the ratio of side a to h, as 
shown in Figure 8-10. It's easy to see that for angles near 90 degrees, 
the tangent increases to infinity, and for this reason it's hard (if not 
impossible) to graph. The format of the tangent is identical to SIN, 
using radians for the argument. Whereas TAN (A) gives the tangent 
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ratio for a known angle, ATN(A) does the inverse. ATN(A) gives 
the angle from the ratio. Both are used often in higher mathematics. 
( That's what tall math profs play with. ) 



1000 FOR 1=0 TO 89 

1100 A=TAN( 1/57.29578) 

1200 B=ATN(A) 

1300 PRINT 1/57. 29578. B 

1400 NEXT I 



' for to 89 degrees 
" find tan9ent 
'find angle froiri tangent 
' print radians .arc tan (pad) 
''continue for 89 degrees 
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CHAPTER 9 



low to Get It All ©ri Tope 



Cassette tape is a fairly recent innovation for computer systems. 
Previous systems used much more complicated digital magnetic tape 
recorders that vi^ere (and are) very expensive. In this chapter, we'll 
discuss the CSAVE, CLOAD, CLOAD?, INPUT#, and PRINT# 
commands, tape data formats and speeds, blocking of records, files, 
error recovery, and tape backups. 

Tape Commands 

There are three cassette tape commands in Level II BASIC— 
CSAVE, CLOAD, and CLOAD?. The use of these is very straight- 
forward. To save a BASIC program, set the cassette recorder level 
to the proper setting, revidnd the tape to the beginning ( or a known 
point using the cassette counter), set the tape recorder controls to 
Record, and type in CSAVE "name". The BASIC program will be 
written out to cassette tape in roughly the same fashion that it is 
stored in memory. 

To reload the program or any other program stored on cassette, 
reposition the recorder to the beginning of tape ( or the counter po- 
sition), set the recorder control to Playback, and type in CLOAD 
or CLOAD "name". The BASIC program will be read into RAM. 

Simple and foolproof . . . What could go wrong? Well, a couple 
of things. First of all, make certain that you are past the leader (the 
non-magnetic material at the beginning of the tape) on the cassette. 
Many tape recorders have trouble recording data on the leader 
(that's a joke, son!). Secondly, make certain that the level setting 
on the tape recorder is at the recommended value for the type of 
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recorder you're using. It may take some experimentation to find the 
optimum level for consistently good writes and reads. Thirdly, not 
only must you be clear of the leader on the tape, but it's a good 
idea to erase a portion of the tape to "bracket" the starting point, 
as shown in Figure 9-1. The reason for this third point is to be 
found in the general tape format that's used for Level II tape op- 
erations. 



LEADER 



HEAD 



BYPASS LEADER 



LEADER 



HEAD 



ERASE TAPE 



LEADER 



HEAD 






START IN MIDDLE 
OF ERASED AREA 



ERASED 
Figure 9-1. "Bracketing" tape writes. 

Follow the Leader 

All tape operations write data to the cassette by first writing 
255 bytes of zeroes and by then writing a single byte of a value 
of 165, as shown in Figure 9-2. The remainder of the write contains 
the BASIC program or data to be written. On a subsequent read 
(CLOAD), the tape read routine expects to find zeroes initially, fol- 
lowed by the 165 value. As a matter of fact, it uses the 165 byte as 
a "synchronization byte" or "sync byte" so that it knows where the 
data starts. 

Data is written on the cassette serially as a long string of binary 
data. (There's that darn binary again!) The 255 bytes of zeroes and 
the one byte of 165 result in 2048 bits of "leader," as shown in 
Figure 9-2. When the CLOAD is performed (or when any tape 
read is performed), the read goes something like this: 

1. A bit is read. 

2. The tape input routine moves this bit left into an 8-bit value. 

3. The value is compared to 10100101 (165). 
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"165" 

SYNCHRONIZATION 

BYTE 



0000000000000 



00000010100101 



DATA 
STARTS 



255 BYTES /, 

OF ZEROES <sP 

TAPE MOVEMENT 

Figure 9-2. Tape format. 

4. If the value is not equal to 10100101, step 1 is again performed. 
If the value is 10100101, step 5 is performed. 

5. Tape input routine prepares to read data. 

You can think of this entire operation as moving an 8-bit "windovi'" 
along the stiing of leader bits until the 165 "sync byte" is found, as 
shown in Figure 9-3. The tape input routines then know exactly 
where the data is on the tape. The obvious reason for this is that 
the tape cannot be accurately positioned manually because each bit 
occupies about 1/250 inch on the tape and the tape must also be 
"brought up to speed." 

To get back to our original discussion on erasing the tape to 
bracket the starting point . . . What if we started in the middle of 
"garbage" data before reading the tape? This could occur if we had 
previously recorded data on the tape and repositioned the tape 
sometime before the actual start of the new- leader, as shown in 
Figure 9-4. Now, if the data included any 8 bits of data in the se- 
ries 10100101, the tape input routine would be fooled into thinking 
that this was a legitimate sync byte and would then start reading 
data, which would be garbage. The chances of this happening are 
about one in 1 inch of tape. So . . . please follow our advice about 
bracketing the starting point on writes, or at least reposition the 
counter slightly past the point at which writing started. {We'll he 



ZERO BITS 
OF LEADER 

\ 



10100101 



^00000 



START OF 
DATA 

/ 



00101 ^ 



\ 



o 

TAPE MOVEMENT 



;-BIT WINDOW 

LOOKS FOR 1 1 1 1 

"SYNC" BYTE 



Figure 9-3. Synchronization operation. 
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ERRONEOUS 
START OF DATA 



"GARBAGE" DATA 



10 10 10 1 



)l 1 1 1 1 1 1 10 10 10 1 1 1 0^ 



o 



ERRONEOUS 
SYNC BYTE 



TAPE MOVEMENT 

Figure 9-4. Synchronization problems. 

sending around our armed guard soon to RND (users) to remind 
ijou . . .) 

Returning to the CSAVE and CLOAD commands, let's write out 
a short program. The shortest program I know of is 

100 REM 

CSAVE this under "SHORT" and then CLOAD it in. Time the op- 
eration. The entire operation took about 5 seconds. Most of the time 
in this case is devoted to writing out the 255 bytes of zeroes. It's 
easy to figure out the time involved in writing out any known length 
of data. We know from diligent study of our Radio Shack manuals 
that Level II records at 500 baud and that 500 baud (in this case) 
is about 500 bits per second. The amount of data per second, then, 
is roughly 500/8 bytes, or 62.5 bytes per second. The leader of 255 
bytes would therefore take about 255/62.5 or about 4 seconds to 
write. We'll be using the 62.5 bytes per second in later discussion, 
so it might behoove you to take this constant and have it engraved 
on a wall plaque for reference in later reading . . . (we'll wait while 
you do . . .). 

Why Is There a Question Mark After CLOAD?? 

We'll be discussing this subject shortly, after we give a definitive 
statement about truth and beauty. The question mark marks this 
CLOAD as a "check" CLOAD. As you know from some late-hour 
CLOADS, one of the things that always seems to occur (especially 
at the end of the day) is to finish debugging a BASIC program, 
CSAVE it on tape, CLOAD it in again, and have it give an error 
part way through the load. 

Unfortunately, at this point the program cannot be recovered, 
and you don't have an old copy. Ah yes, the trials of a programmer. 
. . . The CLOAD? is a well-thought-out command to enable you to 
compare what you have CSAVED with the program currently in 
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RAM (without destroying the program in RAM). Using CLOAD? 
will result in many extra hours of sleep {I'll go for that!). 

While we're on the subject, let's pass on some more quick advice. 
One can never have too many backups. Many times, I've been work- 
ing late evening hours in a computer installation and seen the com- 
puter systematically eat up the current program and many of the 
backups. If you're making a CSAVE, it's a good idea to make two 
copies on the same cassette or even on another cassette. Your TRS-80 
may be hungry. 

What's That (Blinking) Asterisk? 

On a CLOAD or CLOAD? (and on other inputs), two asterisks 
are used. One of them blinks on and off for every line of BASIC 
program read. If you have excellent reflexes, you may be able to 
verify that the number of program lines read in is correct during 
a CLOAD operation. 

Using PRINT# and INPUT# 

CSAVE and the CLOAD commands are fairly easy to use and 
understand. The cassette data is made up of the BASIC program 
lines; all data is of about the same format on tape. 

The PRINT# and INPUT# statements, though, are more general- 
purpose. They are used to output variable-length data records to 
the cassette and to input the records into the BASIC interpreter for 
processing. Try the following: 



100 INPUT "READY TAPE"; AS 

200 PRINT #-li"this IS a t 

300 INPUT "readY tape";A$ 

400 INPUT tt-l,B* 

500 CLS 

600 PRINT a 530, B$ 

700 GOTO 700 



■ujait for- position 
'output one record 
'uait for tape pos 1 1 1 on i rr9 
'input one record 
' cl ear screen 
'print input record 
'for di spl av 



This code shows the basic format for outputting and inputting 
cassette data from a BASIC program. The "#" marks the PRINT 
statement as cassette output and the INPUT statement as cassette 
input. The —1 is used to refer to cassette tape unit number 1. (If you 
have an Expansion Interface, it is possible to write to either of two 
cassettes, and allowable numbers in the PRINT and INPUT state- 
ments are —1 and —2. ) 

The operation above writes one record, made up of the string 
"THIS IS A TEST" and the usual leader of 255 bytes of zeroes and 
a sync byte, to the cassette. The record appears as shown in Fig- 
ure 9-6. As you can see, most of the space in the record is made up 
of leader and very little of data. 
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Rewind the tape and run the following program. 

1000 INPUT "READY TAPE»;A« 'uaxt for tape PosH-ioning 

1100 PRINT #-1,11 1.33, 737, "THIS IS A TEST",IE-05 

1200 GOTO 1100 •continually output record 

Let the program run for several minutes. After accumulating sev- 
eral minutes worth of data on the tape, key in the following program, 
and run it after first rewinding the tape. 

2000 DATA 175, 205, IB, 2, 205, 150, 2, 205, '13,2, 183, 3'', 7 

2100 DATA 62, 10, 205, 5 1,0, 24, 240, 205, 5 1,0, 24, 23s' 

2200 AJ="THIS IS A DUMMY FOR FILL'" 

2300 A=VARPTR(A*) ■g^.t ajHre-. of hlor-l- 

2400 B=PEEK<A*l,*PEEK(A+2,*256 'lU t:^^:: Vf ^J i, 

2500 FOR I=B TO B+24 p'setuP Ioop f^r p L 

2600 READ C ,,^^a ^3,,^ 

2900 POKE 16526, (PEEK(A+1,. ^s^_^,.^. j^ t,,,^; „^ ^ddre.-. 

3000 POKE 16527, ( PEEK (A+2). -..tore ms bvt* of addre^.. 

^'^"^ '^LS -that o, ^.,^3,.. j.,-p^gn 

3200 A=USR<0) -call to never return 

The program above reads data files on cassette and displays the 
data on the screen by using a short machine-language program filled 
into the dummy string A$. (We'll learn more about this technique in 
the next chapter.) Every new record is displayed on a new line. 
This program can be used for any data tape. As we can see from 
the data on the display, the format of the data on the tape is as 
shown in Figure 9-5. Each numeric value in the string for the 
PRINT#-1 was written onto the tape in ASCII with one leading 
and one trailing blank, and a comma between data items. The string 
value was written out without a leading or trailing blank. 

The PRINT#, therefore, is really very similar to a print on the 
display or line printer in that it writes out ASCII data rather than 
binary values. This makes the data easy to read for a routine such 
as the one above, but it makes the data storage somewhat inefficient. 
(A binary value of 32767 would take 2 bytes instead of 5 bytes in 
ASCII, for example. ) 

PRINT# will output any number of variables or constants that 
can be contained within a line in the above format. Each list of 
variables for the PRINT will be contained within one record, with 
255 leading zeroes and the sync byte. A record is simply a some- 
what arbitrary collection of variables, logically grouped into a sin- 
gle area. A file of data consists of a number of records of related 
data. If your TRS-80 was used to record time and temperature in 
each record, for example, the Tuesday, September 25, 1979 tempera- 
ture file might contain 48 records, one for every Vz hour temperature 
reading. 

The INPUT# statement is similar in action to a normal INPUT 
statement. It reads the next record from cassette after first discard- 
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\ LEADER (255 BYTES OF ZEROES, SYNC BYTE) \ 




\tlll. 336, -57376, THIS 


IS ATEST,61E-056J 




\ LEADER 




\ 


1 


^6111.336 


67376, THIS IS A TEST, tlE-OStJ 




ETC. 





RECORD 1 



RECORD 2 



Figure 9-5. Tape data formats. 

ing the zeroes and detecting the sync byte. It separates the ASCII 
data items by looking for commas. It expects to find exactly the same 
number of data items as there are on the INPUT# line and in the 
same format. If the number of data items in the record does not 
match the number specified on the INPUT# line, an OD (Out of 
Data) error may result. If the types of data items do not match, an 
FD (bad File Data) error results. The input routines in the BASIC 
interpreter convert the ASCII data found in the record to the vari- 
able types listed in the INPUT# line. 

Now that we know something about the data format used by 
Level II BASIC, we can accurately predict how long it will take 
to read and write data from cassette. This is very important, since 
the cassette is a relatively slow-speed device, operating at data 
transfer rates 500 times slower than a TRS-80 floppy disk. It will 
benefit us to spend some time discussing some thoughts about cas- 
sette space, speed, and packing. ( Sorry, I couldn't find another "s" 
word for alliteration. ) 

Space, Speed, and (S)Packing 

First of all, let's consider how much data can be stored on a cas- 
sette. If we write 62.5 bytes per second to a cassette, then we have 
the following absolute storage capacities for one side of a C30 cas- 
sette and a C60 cassette. 

C30 = 15 minutes X 60 seconds X 62.5 bytes = 56250 bytes 

minute second 

C60 = 2 X C30 = 112500 bytes 

We say absolute because this would be the storage capacity if the 
cassette were used to read or write one huge record of this size with- 
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out inter-record gaps of zeroes and a sync byte. If we want to find 
out how much record data can be put on the cassette, that's another 
story. We must really figure that out for each individual program 
that writes to cassette. Let's see how we do it in a sample case. 

Suppose, to use the weather analogy again (it's always fair 
weather when good data gets together) . . . Let's say that we have 
the following PRINT# statement for weather data 

TOO PRINT #-l,MO,DA,YR,TM,WS,BP,WD 

The variables are MO for month, DA for day, YR for year, TM 
for temperature, WS for wind speed, BP for barometric pressure, 
and WD for wind direction. If we assume 2 digits for month, day, 
and year, and four digits plus decimal point for TM, WS, BP, and 



00000000 



±Mii?lwLsYNC 



tMOt),-BDAt .iYU .t 



TM, TMt) .tiWS.WSt) ,6 



BP.BPfi.tWD.WDtOO 



256 BYTES 
OF LEADER, 
SYNC 



48 BYTES 
OF DATA 



Figure 9-6. Example of record format. 

WD, then we have records that look like Figure 9-6. Each record 
will contain about 48 ASCII bytes of data plus 256 bytes of leader 
(zeroes and sync byte) for a grand total of 304 bytes. Now, how 
many of these records can we get on a single side of a C60 cassette? 
Easy . . . 
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1^ = 370 records 
304 

Of course, in actual practice the number of ASCII characters per 
variable may vary, trailing zeroes will be discarded, and so forth. 
Still, we can get a pretty good idea of the number of records the 
tape will actually hold by doing this type of analysis. Another ap- 
proximate way to calculate the number of records is to assume that 
each record is about 5V4, seconds long. Using this approximation and 
knowing that there are 30 X 60 = 1800 seconds per side of a C60 
cassette, we can approximate 340 records. This is not too far off; 
the smaller the number of variables in the record, the more accurate 
this method is, of course. 

Now, just for fun, let's try packing data. Packie Data . . . wasn't 
he Roy Autrey's sidekick? No, we said packing data, another data- 
processing buzzword. When data is packed or blocked, more than 
one logical record is put in each physical record. We can put two 
weather readings into each record very easily using arrays, by a 
statement such as 

1 00 PRINT # - 1 ,MO(l),DA(l),YR{l),TM(l),WS(l),BP(l),WD(l),MO(l + 1 ),DA{I + 1 ),YR(I + 1 ), 
TM{I + 1 ),WS(H- 1),BPCH- 1 ),WD(1 -M ) 

This writes the first group of variables followed Immediately by a 
second group of variables. How much data storage have we gained 
by this approach? The size of each record is now 256-f48+48 bytes, 
or 352 bytes, and the number of records is 

112500 „._ , 

= 320 records 

However, since each record holds 2 sets of data, we have the equiva- 
lent of 640 records, 170% of the number in the first case! 

The practical limit is determined by two factors. The first is the 
maximum size of the statement line (240 characters); the second is 
the maximum record length ( 240 data characters or 596 total bytes ) . 
The equivalent number of records for various blocking factors is 
shown in Table 9-1. For example, in the case of records blocked 
6 sets of variables to one record, we can squeeze 1242 sets of vari- 
ables onto one side of a C60 cassette. Quite an improvement over 
370 for an unblocked record! Of course, the smaller the size and 
number of variables, the greater the blocking factor can be, up to 
the limit of the statement line length or maximum record length. 

We can say some interesting things about speed when records are 
blocked. There is a direct relation between the blocking factor and 
speed of access of any record; the more blocking employed, the 
faster we will be able to read in the data. Using a blocking factor 
of 6, for example, the 370th set of variables is about 30% "down 
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Table 9-1. Blocking Factor Versus Data, Sample Case 









Number of Records 






Maximum Numbar of 


Times Blocking Factor 


Blocking 


Number of 


Records, One Side 


(Equivalent Number 


Factor 


Bytes/Record 


of C60 


of Variable Sets) 


1 


304 


370 


370 


2 


352 


320 


640 


3 


400 


281 


843 


4 


448 


251 


1004 


5 


496 


227 


1135 


6 


544 


207 


1242 



the tape" or about 9 minutes, while it is at the end (30 minutes) 
of an unblocked tape. 

Sequential Cassette Files 

Is it practical to use cassette tape to hold data files for processing? 
It all depends on the type of data file. If we want to process the 
weather data we were discussing previously and have to find rec- 
ords at random, then it is impractical to store the records on cassette 
tape, because each time we require a new record we have to inter- 
vene manually and rewind the tape to the beginning of the cassette 
before the search. An example of this access of random records 
would be a user requesting the weather data for July 27 at 12:30 pm, 
then the data for June 10 at 10:00 am, then the data for March 11 
at 5:00 am. The records are ordered on the tape in sequential fash- 
ion based on the date and time. Each search for a random record 
takes between no time and 30 minutes, with an average of 15 min- 
utes (assuming one side of a cassette completely filled with data). 
Fifteen minutes to access a record is intolerable, even for patient 
TRS-80 programmers, and the manual intervention is also a nuisance. 

If, however, we want to compile a list of all times when the tem- 
perature was below -30 degrees and a second hst of all times when 
the wind speed was above 20 miles per hour, this is a relatively easy 
and practical problem. One pass through the cassette could yield 
two lists with the required data in about 30 minutes, not an unrea- 
sonable time, especially when the manual intervention of rewinding 
is not required. 

The second type of processing is sequential in nature. Cassette 
data files lend themselves fairly well to sequential processes, but 
not at all to random processes. Cassette data files can efficiently 
hold any data that can be ordered and processed sequentially. 

It's easy to see how sequential files can be generated. An initial 
set of records is input into memory, blocked, and then output to 
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the cassette in ordered fashion. How are new records merged or old 
records modified or deleted? 

If your svstem has only one cassette recorder, then the size of the 
file is limited by the amount of data that can be held in memory 
and processed. Assuming that about half of the record is data and 
half is leader (512-byte record), then we have about 45,000 bytes 
maximum that we could put on one side of a C60 cassette. That 
would stretch the hmits of a 48K Level II BASIC system, since we 
have about 48,340 bytes initially without a program to process the 
data, but it gives some clue as to the maximum amount of data we 
can handle with one cassette. In this case, all of the data records on 
the cassette would have to be read into memory, the data processed 
by adding new records, modifying old records, and deleting old rec- 
ords, and a new cassette rewritten after the processing was done. 

I hear a strident voice protesting {Guard! Confiscate his C60 cas- 
settes-leave only the CVzs!). No, data cannot be rewritten over rec- 
ords on the tape, for two reasons. First of all, there is that manual 
intervention again to reposition the cassette to the start of the record 
to be modified by rewriting. Secondly, although there are expensive 
incremental tape recorders for computer use, an audio cassette can- 
not be repositioned accurately enough to guarantee that a new rec- 
ord exactly overwrites the old. (Remember the possible erroneous 
sync byte problem we discussed earlier?) The only way to update 
an old file with new data is to rewrite all of the records after they've 
been modified. 

Two Cassettes Are Better Than One 

Having two cassettes simphfies the file update problem consider- 
ably. Of course, an Expansion Interface is necessary for operation of 
the second cassette. One cassette is cassette number -I, and the 
second is cassette number -2. The cuiTent transactions, whether 
they are deletions, modifications, or additions, are input to the sys- 
tem from the keyboard (or from a third cassette). Now the records 
from the old master file (-1) are read one at a time and rewritten 
to the new master file ( -2) . If a record is to be modified, it is modi- 
fied after it is read into memory, and rewritten to the new master 
file. If a record is to be deleted, it is not written to the new master. 
If a record is to be added, it is added between the two records of 
the old master file. 

The time involved to update an old master file into a new master 
file on the second cassette is twice that of working with one cassette, 
but the entire operation can go very smoothly and is fairly efficient 
for sequential files. 
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CHAPTER 10 



To Err Is Human 



We're certain you, like the author, hardly ever make mistakes 

In spite of that, we'll be discussing some of the common errors in 
Level II BASIC programs in this chapter. We'll also talk about some 
very handy features in BASIC that allow the computer to handle 
errors automatically. Why is this important? Suppose you've devel- 
oped a sophisticated BASIC program that does everything but tuck 
you in at night. You have self-prompting messages, menus, and a 
number of other things. In the course of running the program, how- 
ever, let's say you enter some invalid data which results in total 
sales being divided by a number-of-months variable that is equal 
to 0. Suddenly the program spits out "/O ERROR IN 1088," and 
you sit there dumbfounded. (Or at least sit there for about 20 milli- 
seconds before starting to scream. ) 

BASIC has a built-in automatic error-handhng provision that can 
avoid problems such as this. It also provides the ability to simulate 
the errors to check out the error logic itself. 

We'll also give you some homespun advice in this chapter on 
general debugging philosophy, and we'll talk about some of the 
built-in aids to debugging-such as the trace capability. 

Unprintable Errors and Other Types 

Our favorite error type is "unprintable error"; that's exactly the 
way we feel about all errors! The unprintable error and all of the 
other types are listed in Table 10-1. Let's discuss each of them and 
see how they are generated. 
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Table 10-1. Level II BASIC Error Codes 



Error 






Code 




Error Dascription 


1 


NF 


NEXT without FOR 


2 


SN 


Syntax error 


3 


RG 


Return without GOSUB 


4 


OD 


Out of data 


5 


FC 


Illegal function call 


6 


ov 


Overflow 


7 


OAA 


Out of memory 


8 


UL 


Undefined line 


9 


BS 


Subscript out of range (bad subscript) 


10 


DD 


Redimensioned array 


11 


/O 


Division by zero 


12 


ID 


Illegal direct 


13 


TM 


Type mismatch 


14 


OS 


Out of string space 


15 


LS 


String too long 


16 


ST 


String formula too complex 


17 


CN 


Can't continue 


18 


NR 


No RESUME 


19 


RW 


RESUME without error 


20 


UE 


Unprintable error 


21 


AAO 


Missing operand 


22 


FD 


Bod file data 


23 


L3 


Disk BASIC only 



One of the most straightforward errors is the UL, or "undefined 
line" error. This occurs when a statement line reference is made to 
a line that doesn't exist anywhere in the program. 



1000 GOTO 2000 
1010 A = 2*3.2 + ZZ 
3000 PRINT "TOTAL = 



'go to 2000 
'get total 
'print it 



The code above, for example, would result in "UL ERROR IN 1000." 
The SN, or syntax error, is another easy type of error to under- 
stand. A syntax error occm's when the format of a statement line is 
incorrect. Many times this occurs if the number and type of paren- 
theses are incorrect. This ranges from simple statements such as 

100 X=A(5/B 

to complex giants such as 

100 ZZ=(RIGHT(2B$,{A-2)*3)) 

The number of right parentheses must always match the number 
of left parentheses. It's a good idea to get into the habit of count- 
ing and comparing parentheses in long, complex statement lines. 
It's easy to miss an internal parenthesis. Syntax errors are also caused 
by other errors in format such as 
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100 A=B//C 
or 

100 A$ = LEFT$(B$) 

Syntax errors are a kind of catchall for every type of statement for- 
mat error. 

The NEXT without FOR error, NF, and RETURN without 
GOSUB, RG, are two program-format errors that are also obvious. 
NF occurs when a loop is improperly set up without a FOR state- 
ment, or the program branches to a point where a NEXT is to be 
executed without being currently in a loop. An example of this is 

100 GOTO 300 'goto 300 



200 FOR 1 = 1 TO 300 
300 PRINT 



'start of loop 
'print index 



400 NEXT L 'continue 

The RG is similar; a RETURN is to be executed without currently 
having called a subroutine. 

OD, out of data, occurs when READ statements have read data 
values until the end of all data has been reached. As you know from 
previous chapters, all DATA statements anywhere in the program 
constitute one table of DATA values. When a RESTORE is done, 
a pointer is set back to the beginning of the DATA. Subsequent 
reads read one data value for every item in the read list. An easy 
error to make is to have a dummy terminating value to mark the end 
of the DATA values and then not put in enough "dummies" to com- 
plete the READS for multiple items. For example, suppose we are 
reading three DATA values at a time and using a -1 to mark the 
end of the values. 

100 READ A,B,C p.,ead 3 data values 

i™S r '^="-' ™^ -terminator is -1 

^■00 PRINT "A=";A,-B="-,B.>C=";C -print value. 

^50 faoro IBB L.g f ^ ^ . 

300 DATA 1,2, 3, 4, 5, 6, 7,8, '5.-1 ' 

The logic of the above program is flawed, since the last READ at- 
tempts to read the next three values and can find only one. An OD 
error results. 

An illegal function call error, FC, occurs when you're using the 
BASIC functions and specifying invahd arguments. For example, 
what is the square root of a negative number? The code 

100 A = SQR(-23) 

Will produce an FC error. Another type of invaHd argument pro- 
ducmg the same results is a graphics related 

100 SET(223,5) 

or a matrix related 

100 B=A{-1,0) 
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The OV error, overflow, results when a data value is too large for 
the variable involved. As we saw in an earlier chapter, all variable 
types have their limits, beyond which they will not be pushed. 
Trying to INPUT a value greater than +32767 or less than -32768 
will result in an OV error for 

100 INPUT A% 

as will attempting to input 1.1E127 for A or A#. 

Choose one from the following: "OM, out of memory" occurs when 

A. The RAM chips are pulled from their sockets. 

B. Bornstein takes a vacation. 

C. The stack builds down into the text/ variable /array area. 

D. The program expands and the text/variable/ array area moves 
into the stack. 

E. A new simple variable expands the text/ variable/ array area 
into the stack. 

F. An array is dimensioned and the text/variable/array area ex- 
pands into the stack. 

G. A CLEAR is performed that expands the string/ stack space 
into the text/variable/array area. 

H. I forgot the question. 

If you chose any of the above, you are probably right. Any time 
the free memory between the text/variable/array area and the stack/ 
string area is small, the action of running the program may dimen- 
sion arrays, clear string space, add new variables, or perform other 
actions to use up the last available memory (see Figure 10-1). 

Anticipating that some users might be prolific coders, the design- 
ers of Level II BASIC were faced with two alternatives: 

1. Let the program gobble itself up, or 

2. Print an OM error. 

They chose the latter. To see how much memory is still left under 
various conditions, you may include a "PRINT MEM" at any point 
in the program. Doing a rough estimate on the amount of storage 
required by arrays also is a help. If you do run out of memory, pos- 
sible alternatives are: 

Reduce the program size by deleting REMarks and blanks, and 
building multiple statement lines. 

Make single-precision variables into integer variables when pos- 
sible, especially for arrays. 

Reduce the string area defined by CLEAR. 

Segment the program into two or more sections. 
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An OS (out of string space) error related to OM occurs when the 
string space allocated by a CLEAR statement is too small to handle 
string manipulations. The string area may be made as large as re- 
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Figure 10-1. Free memory area. 

quired, subject to other storage, so don't hesitate to throw caution 
to the winds and say 

100 CLEAR 20000 

if required. This also eliminates or reduces dynamic string allocation 
in the middle of execution. (You know, the interminable pauses that 
make you think that it's time to visit the repair -center. ) 

The BS, or subscript out of range, error occurs when an array sub- 
script is greater than the dimension value specified in the DIM state- 
ment or is otherwise incompatible. Arrays are specified by DIM val- 
ues that represent the maximum value for the dimension. For ex- 
ample, the statement DIM A (5,5,5) specifies an array that is six by 
six by six with values for each dimension of from through 5. 
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Another array-related error is DD, a redimensioned array. Arrays 
can be dimensioned once and once only, and cannot be redimen- 
sioned. A DIM statement at the beginning of the program sets up 
the array in the array storage area of memory by allocating memory 
space for the array based on the variable type and the size of the 
array. It is not permitted to redefine the array later in the program, 
and, as a matter of fact, that's just gosh-darn bad programming 

practice. 

We've probably all heard our math instructor say that division 
by is not possible or at least "undefined." When the computer at- 
tempts to divide by 0, the answer is the largest possible number 
that can be held in the variable type. This is clearly wrong as the 
answer for the integer calculation 333/0 is not 32767! Just as our 
math instructor did not know what to do when he attempted to di- 
vide a number by 0, neither does the BASIC interpreter, and it pro- 
duces a /O error. 

The ID, or illegal direct, occurs when INPUT is entered as a 
direct command. INPUT A,B is meaningless if not associated with 
a statement line. 

There are three error types associated with strings, TM, LS, and 
ST. TM, type mismatch, occurs when the program attempts to de- 
fine a string variable, a numeric value, or vice versa. 

TOO A$= 12.34 
200 A = "STRING" 

will both produce TM errors. The LS, or string too long, error will 
occur if a string value exceeds 255 characters in length as in 

1000 CLEAR 1000 -clu-ir sti-ing Etoraqc- 

1100 AS="14 CHARACTERS'" '1* char- string 

120B B3;=B*+AS p- concatenate 

1300 PRINT BS 'print concatenated stnns 

1400 SOTO 1200 "-'keep en s.lcgging 

The ST error, or string formula too complex, occurs when the BASIC 
interpreter just cannot handle the machinations of the programmer. 
I have never experienced the ST error (which may say something 
about the sophistication of my coding!). We'll leave it up to you to 
produce samples of string statements that produce this error. 

The CN error, can't continue, occurs when the program has 
reached a logical end and a CONTinue statement is meaningless. 
It is the interpreter's way of saying "THINK AGAIN, HAMMU- 
RABI!" 

The NR, RW, and UE errors will be discussed shortly when we 
discuss the error functions. 

The MO, or missing operand, error occurs for cases where an op- 
eration is specified but no operand exists. The code 
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100 A=(5+32)/ 

will produce an MO error. 

Bad file data, FD, occurs when a cassette read operation is taking 
place and invalid data is read in as a result of bad data on the tape, 
or "glitches" in reading the cassette. Errors such as this are classed 
as recoverable or non-recoverable. A recoverable error means that 
the same data may be reread and recovered. Unrecoverable gener- 
ally means that three (or more) retries were unsuccessful in recov- 
ering the data. 

The last error code, L3, is displayed when a Disk BASIC command 
is attempted without disk. An example of this would be an attempt 
to execute a KILL command to kill a file or a non-existent disk. An 
L3 error would result. 

Trapping the Wild Error 

As we're all aware, the BASIC interpreter stops program execu- 
tion after encountering an error, prints the two-letter error type, 
and returns to a READY condition. This is a reasonable action to 
take in the general case. If you can anticipate the errors that may 
occur, however, you can utihze the Level II Error functions to pro- 
cess the errors and either correct the condition or prompt yourself 
into correcting the condition. The error functions that you have 
at your disposal are the "ON ERROR GOTO" trap (which trans- 
fers to a given statement number for any error), a RESUME state- 
ment (which acts as a type of CONTinue after the error), the ERL 
and ERR/2+1 (which return an error line number and error code 
number, respectively), and an error simulate, the ERROR function. 
Before we discuss how we can trap errors, let's talk briefly about 
what errors we want to trap. 

We could conceivably set up a program to trap (process) all er- 
rors. However, some errors, such as SN, NF, and RG, are clearly 
program logic errors. In other words, the program has not been suffi- 
ciently debugged when these errors occur! It does not make sense to 
process such errors that are involved with program logic. It does 
make sense to process errors that are a result of incorrect data input 
by the user, overflow conditions on input, division by 0, type mis- 
match on input, or bad file data. The error trapping ability is meant 
primarily as a means to make a program "idiot-proof" in the kindest 
sense of the word-to anticipate the normal types of errors that oc- 
cur primarily as a result of operator errors in inputting data. 

Now that we know what errors we want to trap, let's see how we 
go about processing them. First, we'd better take a close look at the 
"ON ERROR GOTO" statement. This statement defines an error- 
processing routine for the interpreter. Henceforth, any error condi- 
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tion will result not in a printout of the error type, but a transfer to 
the line that begins the error processing routine. 

100 ON ERROR GOTO 10000 

informs the interpreter that the error processing routine is at line 
10000 and that any errors that occur should cause an automatic 
transfer to that line. 

The ON ERROR GOTO function may be disabled by executing 
an ON ERROR GOTO statement at any time. By alternating be- 
tween ON ERROR GOTO n and ON ERROR GOTO statements, 
error trapping may be turned on and off depending upon the section 
of the program that is currently being executed. If, for example, the 
program only handles error processing for bad cassette data, then 
any time cassette data is not being INPUT an ON ERROR GOTO 
may be executed to disable the trap. 

The RESUME statement is used to resume normal operation after 
error processing has taken place. There are three formats for the 
RESUME. 

1. RESUME or RESUME causes a return to the statement where 
the error occurred. 

2. RESUME n causes a transfer of control to a specified line num- 
ber n. 

3. RESUME NEXT causes a transfer of control to the line imme- 
diately after the line at which the error occurred. 

We'll show examples for all three using the infamous /O error type. 
First, the RESUME case. 



;B00 


ON ERRi: 


:iR GOTO 2500 


'setup er-rc<r tr-ap 


il00 


A=2/0 




'cant divide by 0' 


.■200 


PRINT ' 


'LINE 2200" 


•print line » 


:300 


PRINT ' 


'LINE 2300" 


' print 1 ine 


l400 


END 




'thi5 15 the end 


;5B0 


PRINT 


"error trap" 


'error trap locati 


;'600 


RESUME 




'resume processing 



Execution of this program causes the error-processing routine Mne 
number to be stored by the interpreter as "2500." A divide by er- 
ror results at line 2100, causing the interpreter to transfer control to 
the error-processing routine at line 2500. This routine prints "ERROR 
TRAP" and then executes a RESUME, which transfers control back 
to line 2100, which causes a divide-by-0 error, which transfers con- 
trol to the error-processing routine at line 2500 which, .... Well, 
anyway, you get the idea. 



3000 ON ERROR GOTO 3500 

3100 A--2/0 

3200 PRINT "LINE 3200" 

3300 PRINT "LINE 3300" 

3400 END 

3500 PRINT "ERROR TRAP" 

3600 RESUME 3300 



'setup error trap locn 

'cant divide t>v 0' 

' print ! ine # 

' pr 1 nt 1 1 ne # 

' this 1 s the end 

'error- trap location 

'resume processiny a 2'3IS2 
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Execution of this version causes an error trap to line 3500, print- 
out of "ERROR TRAP", and a transfer of control to line 3300 with 
termination of the error condition. 



'pB00 on error goto '1500 
4100 A=2/0 



420B PRINT 
4300 PRINT 
4400 END 
4500 PRINT 



4600 RESUME NEXT 



'LINE 4200" 
'LINE 4300" 



'ERROR TRAP" 



setup error trap 
'cant divide by 0! 
'print 1 irie # 
'print line # 
'this IS the end 
'error trap locati 
' resume next 1 ine 



Execution of this version causes an error trap to line 4500, printout 
of "ERROR TRAP", and a transfer of control to the line immedi- 
ately following the line causing the error condition, line 4200. 

Error Processing 

Error processing involves three steps: identifying the error, cor- 
recting the error, and RESUMEing at a logical point. We'll talk about 
the first two, since the third is dependent upon the success in solv- 
ing the error condition. 

There are two statements that we can use to identify the error 
ERL and ERR/2-+-1. ERR/2+1 provides the error code (see Table 
10-1), while ERL provides the line number. The code below prints 
out the error code and line number on which the error occurred. 
Try running this code not only with the /O error, but with other er- 
roneous code at statement 200. 



100 ON ERROR GOTO 500 

200 A=2/0 

300 PRINT "LINE 300" 

400 END 

500 PRINT "ERRORS 

600 RESUME NEXT 



'setup error trap 1 oc 
' naughty. nau9htY I 
'print 1 ine # 
'end program 
ERR/2+i, "ERROR LINE=";ERL 

'resume at next line 



If we only wish to process certain types of errors in our error pro- 
cessing routine, we can easily eliminate the catastrophic errors such 
as NEXT without FOR, syntax, and others by comparison of the 
error type. 



1000 ON ERROR SOTO 1400 

1100 A=2/0 

1200 PRINT "LINE 1200" 

1300 END 

1400 A=ERR/2+l 

1300 IF AOll AND A013 AND A<:>22 

1600 PRINT "/0 OR TM OR FD ERROR" 

1700 RESUME NEXT 

1800 ON ERROR GOTO 

1900 RESUME 



'setup error trap loc 

'again*? ' 

'print 1 ine tt 

'end program 

'get error code 

1B00 

'was one of the three 

'resume at next line 

'reset error trap 

'resume at error line 



The above code processes only a /O, type mismatch, or bad data 
error by testing the error code ERR/2-H. If one of these three er- 
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rors occurs, a message is printed, and the program resumes at the 
next line following the error. If none of these errors occurs, the error 
trapping is reset by ON ERROR GOTO 0, and a RESUME causes 
Hne 1100 to be re-executed resulting in the "normal" error type prmt- 
out and the READY prompt by BASIC. 

Having identified the errors we wish to process, how can we cor- 
rect the conditions causing the error? This is really an unanswerable 
question, since it depends so much upon the type of program. It the 
error occurred because of overflow or type mismatch durmg data 
entry, then it is relatively simple to output an error message that 
prompts the user to re-enter the data. In word-processing applica- 
tions an out-of -memory error could result, and suitable action, such 
as "flushing" the text onto cassette, could be taken. Divide-by-zero 
problems may be solved by re-entering the data, also. (Truthfully, 
though, many divide-by-zero problems should be handled earlier by 
checking the data for validity and proper range.) 

An FD error, bad file data, may be hard to handle for cassette. 
A floppy-disk may be easily reread, but cassette file errors call 
for repositioning. A step-by-step procedure may be implemented to 
help the operator reposition the tape for a new try at readmg. After 
three tries or so, some other action must be taken to replace the lost 
data, or the program may have to be terminated. 



Simulating Errors 

The last error function is the ERROR statement, which simulates 
an error code. This is a handy feature for debugging the error trap- 
ping functions. (The question, "What do we use to debug the debug 
of the error trapping functions?" arises, but since we see an endless 
loop appearing, we'll continue.) ERROR n produces a simulated 
error. In the code above, we could have made line 1100 

nOO ERROR 11 

which would have the same effect as a /O error. 

The code below causes simulated errors for error codes 1 through 
23. Each code is printed, and the error trap routine then causes exe- 
cution at the NEXT line following the error line. 



2000 ON ERROR GOTO 2400 

2100 FOR 1=1 TO 23 

2200 ERROR I 

2300 NEXT 

2350 END 

2400 PRINT ERR/2+1) 

2500 RESUME NEXT 



'setup error- trap 

E'lc.op for error codes 

'simulate error 
' continue 

'er-ror processing pr-int 
'resume next )ine 



Now for those three missing error codes, RW, NR, and UE. 
All three are associated with error trapping or simulation. RW is 
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RESUME without error and occurs when a RESUME is encoun- 
tered without a previous ON ERROR GOTO statement. NR is NO 
RESUME and occurs when program end is reached while still in 
an error trapping mode. The last, that !!!$#'!! unprintable error, 
UE, is caused by attempting to simulate an error with an invalid 
error code, as in 



100 ERROR 87 'lll$#*l! 



Debugging 



In the old computer days ten years or so ago when computer time 
was at a premium, the process of debugging a program was com- 
pletely different than it is now on the TRS-80. The procedure then 
(and now at larger computer installations) was to do a great deal 
of "desk checking" of programs before "getting on" the machine. 
Getting on amounted to submitting the program as one of fifty "jobs" 
to be run on the computer installation. When its turn came, the 
program would run, exercise some test data, and "blow up." The 
programmer would then retrieve the new listing and test data and 
try to piece together what had happened in the program. The luxury 
of having a computer to oneself was only infrequently possible, and 
programmers were forced to adapt to this type of debugging. 

In the 

however, and in most personal computer systems, the debugging is 
interactive. A programmer can monopolize the whole system (and 
why not! ) and debug his program until his program runs perfectly. 
Some programmers, ingrained with the procedures of the computer 
dark ages, may sneer at this method of debugging, but it is ex- 
tremely efficient, fast, and with the tools in Level II RASIC, very 
powerful. 

The first step in efficient debugging, however, is good design. 
The program does not have to be written, but flowcharting or list- 
ing the steps may help in the on-line program editing. Rreaking up 
the program into separate modules performing well-defined func- 
tions also helps for long programs. Generally, the more thought 
given to good design, the less trouble there will be in debugging. 

The next step, of course, is entering the program via the edit 
mode. The AUTO feature of the editor may be used to sequence 
line numbers automatically with increments of 10 to allow addi- 
tions of statement lines during debugging. Give some thought also 
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to segmenting the functions of the program. A mailing-list program, 
for example, that has add, delete, modify, read from cassette, and 
write to cassette may be conveniently segmented into 

Command Interpreter and Menus Lines 10-999 

ADD Lines 1000-1999 

DELETE Lines 2000-2999 

MODIFY Lines 3000-3999 

READ Lines 4000-4999 

WRITE Lines 5000-5999 

As sections of code are entered, there is no reason not to debug 
on the spot with a RUN after setting up the proper values. If the 
code segment at 1000-1999 is the add function, for instance, perform 
a RUN 1000 to execute and debug the add function as a separate 
entity. Breaking down the program into small portions for debugging 
purposes will speed up the overall debugging process. 

When the program blows up at a line and an error message of 
"BS ERROR AT LINE 3250" is displayed, don't scratch your head 
and look at the listing. Don't forget that the data causing the blowup 
is still in RAM. Enter a series of PRINT statements ia the command 
mode to print out the current values of the variables causing the 
blow-up. 

>PRINT U,(A*2 + 17) 

This method of dumping the variables at the occurrence of the bug 
may be done as much as required. 

If the bug is still present, put a STOP statement anywhere in the 
program before the line at which the error occurs, and repeat the 
process of displaying the variables to see where the error is intro- 
duced. A type of "binary search" may be used to converge on the 
statements causing the error; if things are all right up to a certain 
point, halve the portion of the program remaining, STOP, and dis- 
play the variables. CONTinue until the bug is found and squished. 

The Trace option may also be used to help in debugging. Trace 
may be turned on by TRON and off by TROFF. A trace on any 
computer system traces the flow of the program by printing loca- 
tions or line numbers that the program follows. The trace capabiHty 
on the TRS-80 is very fast because line numbers are displayed on the 
screen, which is an efficient input/ output device. TRON /TROFF 
may be temporarily embedded in the program to trace only at the 
point at which problems arise. It may also be used to flag tlie pro- 
grammer that a certain section of the program has been erroneously 
entered. 

A "snapshot" capability may also be used in TRS-80 debugging. 
Snapshots differ from traces in that they selectively display loca- 
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<98a2><9a30><9840><984 l>SN*P A= 20 
<984 2>< 9830X 9840X9 84 i>SNAR ,A= 7 
<9842><9830><9B40><984 l>SNSP A= 23 




Figure 10-2. Example of snapshot. 




tions or variables at different parts of the program. Suppose that 
you are having problems with a section of code at line 9830. You 
may invoke the Trace mode to print out the line and PRINT out 
the troublesome variables directly after, and then turn off the trace. 
Every time the program sequences through that portion of the pro- 
gram, you vs/ill get a snapshot of the variables at that point, as shown 
in Figure 10-2. 



9825 TRON 
7330 A=A+1 

9840 I=LEN(A$) 

9841 PRINT "SNAP: A=" !A, 
9S42 TROFF 



After you have found the last error in your program, it's time to 
start debugging in earnest! Not exactly debugging, but exercising, 
actually. Run the program, and try as many combinations of inputs 
and data as possible. Be like playful computer-science students at 
time-sharing terminals who try to "crash" the system! If the pro- 
gram is to be sold or even supplied free to friends, the users won't 
appreciate unexpected crashes of a "completely debugged" program! 
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CHAPTER 11 



on of BASIC Meets the 
achine Code Monster 



Machine language, like English or French, has gone through many 
changes since its inception. During the building of the pyramids, 
machine language consisted mainly of groans and sighs. Later, dur- 
ing the industrial revolution, clicks and whirs replaced the earher 
grunts. Still later, machine language made a transition to a silent 
stream of ones and zeroes fed into a computer. The term machine 
language is somewhat confusing to many BASIC programmers. 
What is it? How can I use it? Why are we asking so many rhetori- 
cal questions? These and other aspects of machine language will be 
revealed in this chapter as we present 



SON OF BASIC MEETS THE 
MACHINE CODE MONSTER 

Alan Load as Dr. Binary 

Sylvia Compari as Gretchen 

Knute Exchange as Bret Wonderguy 

© @ @ 

A Taiitly Production - f Jimed in BASIGvisioii 



What we'll attempt in this chapter is to present the very rudiments 
of machine-language or assembly-language programming and how 
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to interface to assembly-language code using BASIC. For a more 
thorough treatment, see Radio Shack's TRS-80 Assembly-Language 
Programming (62-2006). 

HeUo, Mr. Chips 

The TRS-80 is constructed around a microprocessor called the 
Z-80. The Z-80 semiconductor chip is almost a complete micro- 
computer in a piece of silicon material measuring a fraction of an 
inch on each side. The semiconductor material is etched and pro- 
cessed to contain miniature electronic components— tens of thousands 
of them. 

The Z-80, like its predecessors, has a built-in instruction set or 
instruction repertoire. In the early days of computing when elec- 
tronics were expensive, the amount of circuitry was limited and in 
turn limited the number of instructions that could be implemented. 
The actual instructions that the computer understood were such 
simple primitives as add two 16-bit numbers, subtract two numbers, 
compare two numbers, jump to a new location, and the like. Later,' 
as circuitry became less and less expensive, more instructions were 
added. However, the number and types of instructions had a prac- 
tical limit dictated by their generality. After all, specific instructions 
such as "If this number is 512 or greater, subtract 23" have limited 
application. 

The instruction set in the Z-80 consists of hundreds of instructions. 
At first, the sheer number of instructions seems overpowering, but 
the instructions can be grouped into several dozen different cate- 
gories. Within each category, the instructions are very similar in 
many cases. 

Within the Z-80 are a set of internal registers. The registers may 
be thought of as additional memory locations similar to RAM mem- 
ory. The registers accessible to the programmer are shown in Fig- 
ure 11-1. Instructions within the Z-80 operate between the Z-80 
registers or between registers and memory. Typical instructions 
would be ones such as 

LD A,(1234) Load register A with the contents of memory location 1234. 

LD (17000),A Store the contents of register A into memory location 17000. 

ADD A,B Add register A and B and put results in A. 

JP 1700 Jump to memory location 1700. 

The instruction length varies from one byte for an instruction 
such as ADD A,B to four bytes for an instruction such as LD A,(IX), 
which loads the A register with the memory location pointed to by 
the IX register. The average instruction is about two bytes long. 

Each instruction is represented by an operation code (opcode) 
and operands vdthin the instruction. For example, the 8-bit code 
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-TWOBYTES- 



(— ONE BYTE— 





A REGISTER 




F REGISTER 




H REGISTER* 




L REGISTER* 




B REGISTER** 




G REGISTER** 




D REGISTER*** 




E REGISTER*** 




A' REGISTER 




F' REGISTER 




H' REGISTER* 




[■REGISTER* 




B'REGISTER** 




C REGISTER** 




D'REGISTER*** 




E' REGISTER*** 


IX REGISTER 


lY REGISTER 


SP REGISTER 


PC REGISTER 


1 REGISTER R REGISTER 



GENERAL 
REGISTERS 
NORMALLY 
USED 



GENERAL 
REGISTERS 
NOT NORMALLY 
USED 



INDEX 
REGISTERS 
STACK POINTER 
PROGRAM COUNTER 
INTERRUPT REGISTER, 
REFRESH REGISTER 
NOT NORMALLY USED 
BY PROGRAMMER 



DENOTES REGISTERS 
USED TOGETHER AS 
"REGISTER PAIRS" 

Figure 11-1. Z-80 registers. 

10000001 represents the instruction "Add the A register and C regis- 
ter and put the result in the A register." To make instructions such 
as this easier to write down, every instruction has a mnemonic form, 
such as "ADD A,C." The number of bits for each instruction, then, 
varies from 8 for a one-byte instruction to 32 for a four-byte instruc- 
tion. The binary code for each instruction is called the machine- 
language version of the instruction. 

One could code a program in machine language. The stream of 
ones and zeroes could then be fed into TRS-80 RAM by POKEs 
and would execute as a machine-language program if properly called 
by BASIC or by a SYSTEM command. 

You can always recognize programmers who worked in the 1950s 
by their eyeglass or contact-lens prescriptions. Coding in ones and 
zeroes is somewhat tedious, to say the least. Machine-language 
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coding was quickly replaced by a form of coding called assembly- 
language coding. In this scheme, instructions are still coded from 
a table, but the table is referenced by an assembler program rather 
than a programmer. The programmer supplies text mnemonics such 
as "ADD A,B," and the assembler program automatically assembles 
them into the proper machine-language form. 

The TRS-80, being a sophisticated computer, has quite a nice 
interactive Assembler/ Editor which can be used to assemble ma- 
chine-language programs of several instructions to thousands. The 
resulting machine-language code can then be manually POKEd into 
RAM or be input by means of a SYSTEM or T-BUG tape. We'll be 
discussing both the use of SYSTEM tapes and the POKE method 
in this chapter. But first . . . 

TRS-80 Memory Layout 

Before we use any machine-language routines, we must get an 
idea of the memory layout of the TRS-80. That way we will not be 
(to use a technical term) clobbering any machine-language program 
with which we are interfacing. Figure 11-2 shows the BASIC m.em- 
ory layout. 

The fii-st 12K bytes of the 64K bytes (remember, K=1024) of mem- 
ory locations available to the TRS-80 are dedicated to the ROM 
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LOCATION 





12287 
12288 



16384 



12K 

ROM 
LEVEL II BASIC 
INTERPRETER* 



IK VIDEO MEMORY* 



'WORKING STORAGE" 



BASIC PROGRAM 
TEXT 



SIMPLE 

VARIABLES 

t 



ARRAYS 



FREE 
MEMORY 



65535 



16K 

ROM 

MEMORY, 

RESERVED 

ADDRESSES. 

VIDEO MEMORY 



16K RAM 



STACK 



STRING 
STORAGE 
AREA** 



MACHINE-LANGUAGE 
RESERVED AREA** 



16K RAM 



I BUILDS 
I "UP" 

i BUILDS 
I "DOWN" 

*F1XED 

"FIXED UNDER 
USER CONTROL 



16K RAM 



Figure 11-2. BASIC memory layout. 
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containing the Level II BASIC interpreter. ROM, of course, is 
Read-Only Memory and can't be changed. The next 4K is a mix- 
ture of video display memory, which is IK bytes long and located 
at the end of the 4K segment, and dedicated memory addresses. 
The dedicated memory addresses do not exist as memory but are 
detected by such system devices as printer logic and the RS-232 
interface. 

The next 4K to 48K of memory is RAM, or Random Access Mem- 
ory. RAM can be read from and written into (Editors Note: Never 
use a preposition to end a sentence with!). It can be loaded with 
programs or data or can be altered by POKEs. Depending upon the 
size of your system, you may have 4K, 16K, 32K, or 48K of RAM. 
The memory location of RAM starts at 16384 and continues to 65535 
for a 48K (RAM) system. 

During the use of Level II BASIC, certain areas of the RAM are 
used by the interpreter, as shown in Figure 11-2. The first portion 
of RAM contains "Working Storage," followed by BASIC program 
text, simple variables, and arrays. As a BASIC program is created, 
this area expands as new variables and statements are added; it is 
not static, but "grows" toward high memory addresses. 

At the same time the text, variables, and arrays are using up low 
RAM, the string space and stack are using high memory. A CLEAR 
statement clears a fixed area at the top of RAM for use as string 
working storage. Immediately below the string space is the stack 
area. The stack area is expanding and contracting as the BASIC in- 
terpreter is run, but uses only several dozen bytes of memory or so 
at any given time. 

The area between the stack and arrays is free memory. The figure 
is somewhat misleading, as free memory usually constitutes a major 
portion of available memory, dependent upon the system memory 
and program size. 

The area of memory immediately at the end of RAM may be re- 
served for use of machine-language code or any other use. When the 
Level II interpreter asks (in its inimitable fashion) 

MEMORY SIZE? 

and patiently waits for your answer, it takes the value specified and 
reserves the RAM area from "top of memory" to the specified value. 
Specifying 63000 in a 48K system, for example, would reserve RAM 
locations 63000-65535. These locations would never be used for 
string or stack storage, or for any other interpreter use. If no value 
is entered, no area is reserved. 

How much memory can be reserved by the use of MEMORY 
SIZE?-any reasonable amount. The BASIC interpreter must have 
some memory available for program storage, variables, arrays, stack, 
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and string space, but as long as it has enough to cover every condi- 
tion during BASIC program execution, the reserved area may be as 
large as necessary. 

SYSTEM Tapes 

Now that we have a little knowledge about the TRS-80 memory 
layout and machine code, let's disregard the homily and do a dan- 
gerous thing . . . create and use our first system tape. For this exer- 
cise, we'll create a short assembly-language program to white out 
the screen (do you have those stop watches ready?). 

Our first step is to hand assemble the program using a table of 
opcodes or to use the Radio Shack Editor/ Assembler to create the 
desired program. 

The process of designing, coding, and debugging in assembly 
language may be quite involved, and we can't explain how to do 
it in this one chapter. The end result of the designing, coding, and 
debugging effort is shown in Figure 11-3. It is an assembly-language 
listing representing the assembly-language program to perform the 
screen white-out. 

We will explain this one program fully to help you understand 
assembly language a little better; we'll bypass complete explanations 
of other assembly-language programs presented in the chapter. You 
may ignore the actual assembly-language code and concentrate on 
the techniques of interfacing to assembly-language subroutines, if 
you wish. 

The left-hand column of Figure 11-3 represents the memory loca- 
tions where the program resides. These hexadecimal values are the 
locations for the machine-language code found in the next column. 

MEMORY LOCATIONS 
FOR INSTRUCTIONS 







MACHINE-LANGUAGE 












INSTRUCTIONS 
















LINE NUMBERS 




SOURCE CODE 


^1 A0O 


i / 

00 1 00 


ORG 


1E1944 




4A00 


■21003C 


00110 WHITE 


LD 


HLi 15300 


VSTARl OF SCREEN 


^A03 


1 10004 


00120 


LD 


DE. 1024 


M024 CHARACTER POSITIONS 


4AQ6 


3taF 


00130 LOOP 


LD 


A. 191 


;ALL ON 


4h0B 


77 


00140 


tn 


i HI 1 . A 


: STORE ALL ON 


4A09 


23 


00150 


TNC 


HL 


LINCREMENT DISPLAY ADDREiiS 


4A0A 


IB 


00160 


DEC 


DE 


; DECREMENT it OF BYTES 


''+AfclB 


7 A 


0017B 


LD 


A.D 


;GET MOST SIGNIFICANT 


4ABC 


B3 


00 1 80 


OR 


E 


IMERGE LEAST SIGNIFICANT 


4AV1D 


20F-,' 


00190 


,JR 


NZtLOOP 


;L<:iOP IF NOT 10'^4 


'lABF 


C9 


00200 


RET 




-, RF;TURN if DONE 


0000 


1 TOTAL t 


00210 


END 


N ' 




000Oii 


RRORS ' "~^ 


^ ' 


' 






LABELS 


MNEMONICS OPERANDS 


REMARKS 


LOOP 


4A06 


COLUMN 


COLUMN 


COLUMN 


COLUMN 


WH 


ITE 


4A00 











Figure 11-3. Assembly-language screen white-out. 
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The machine-language code consists of two, four, six, or eight hexa- 
decimal digits representing one to four bytes of a machine-language 
instruction. The next (third) column is a line number, identical to 
BASIC line numbers. The remainder of the listing in the figure repre- 
sents the source code of the program. 

The assembly-language source code consists of four parts. The 
fourth (extreme right) column has the comments of the program. 
This column is optional. The second column of the source code has 
the actual Z-80 mnemonic form of the instruction. This is a shorthand 
representation of the instruction just as in BASIC statement types. 
An instruction may have several operands, and these are contained 
in the next column. The left-hand column of the source code holds 
optional labels which are used in place of Hne numbers for jumps 
(equivalent to GOTOs). 

Now for the actual program to white out the screen . . . 

Line 100 loads a CPU register (HL) with 15360, the address of 
the video display start. A second CPU register (DE) is then loaded 
with 1024, the number of characters on the screen. HL will be used 
as a pointer to 15360-16383 throughout the program loop just as a 
BASIC variable HL might be used for a POKE HL value. DE will 
be used as a count of the number of screen positions actually whit- 
ened, just as in the BASIC statement "FOR DE = 1024 TO STEP 
-1". 

Lines 120 through 180 constitute a program loop. The loop is 
performed 1024 times. Each time through the loop, the following 
actions occur. 

1. The CPU A register is loaded with 191, a value representing a 
graphics "all ON" (line 120). 

2. The contents of A ( 191 ) are stored into the video memory lo- 
cation pointed to by HL (line 130). 

3. The pointer in HL is incremented by 1 to point to the next 
video memory location (line 140). 

4. The count in DE is decremented by 1 (line 150). (When it 
reaches 0, the loop will terminate.) 

5. The count in DE is tested for (lines 160 and 170). 

6. If the count in DE is not zero, another loop is made back to 
label LOOP. If the count is zero, the next instruction at line 
190 is executed. (Line 180.) 

7. When the count is zero after 1024 times through a loop, a 
RETurn instruction is executed to return to the BASIC pro- 
gram. 

Where do we want this program to reside in RAM? To handle 
the case of every reader (unless someone out there has one of the 
early 3.3K TRS-80 systems), we'll plan on putting this program at 
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RAM location 20300, which is close to the top of a 4K RAM system. 
The starting location for machine-language routines is important, be- 
cause the codes for the instruction operands vary according to where 
the instructions are placed in memory. Unlike BASIC, machine 
language references are to absolute memory locations, rather than 
line numbers of statements. As an interesting point, though, it just 
so happens that this particular assembly-language routine is relocat- 
able to any part of RAM; it does not have to be reassembled. All of 
the machine-language routines in this book are relocatable in this 
fashion. 

There are two alternatives to using an assembly-language pro- 
gram after it has been properly assembled, loading a SYSTEM tape 
created by the Radio Shack Editor/ Assembler or using the Hsting 
values after assembly by POKEing them into memory. These two 
alternatives will hold true for all programs in this chapter. Well 
explain how to use both methods for this program to white out 
the screen. 

The first alternative is assembling and loading a SYSTEM tape. 
If we take the source program from Figure 11-3 and key it into the 
Radio Shack Editor /Assembler, not only will we get the listing of 
Figure 11-3, but the Editor/ Assembler will generate a file on cas- 
sette called the SYSTEM (object) file that can be loaded by a 
SYSTEM command. To load the SYSTEM tape, type the following 
after initializing BASIC: 

MEMORY SIZE? 18944 

RADIO SHACK LEVEL II BASIC 

READY 

>SYSTEM 

°?(Name of tape) 

The SYSTEM tape created by the Editor/ Assembler will now load 
under the name specified to the Editor/ Assembler (or "NONAME" 
if none was specified). To get back to BASIC, hit BREAK after the 
tape has loaded. 

The second alternative is to POKE the machine-language values 
from the assembly Usting. After the assemble, we have two columns 
on the assembly listing that represent the locations for the machine- 
language code (starting at 18944) and the machine-language code 
itself. 

In this program, the following machine-language code was gen- 
erated by assembly: 

Location 

4A00 (18944) 
4A01 

192 



Hexadecimal 




(From Fig. 11-3) 


Decimal 


21 


33 


00 






4A02 
4A03 
4A04 
4A05 
4A06 
4A07 
4A08 
4A09 
4A0A 
4A0B 
4A0C 
4A0D 
4A0E 
4A0F 



3C 
11 
00 
04 
3E 
BF 
77 
23 
IB 
7A 
83 
20 
F7 
C9 



60 

17 



4 

62 

191 

119 

35 

27 

122 

179 

32 

247 

201 



We have converted the hexadecimal code to decimal for POKEing, 
as Level II BASIC will only accept decimal values. The hexadecimal 
values may be converted by reference to a hexadecimal-decimal con- 
version table such as the one that can be found in the Editor/Assem- 
bler manual. 

The 16 locations may be loaded by POKEing by simply perform- 
ing a POKE 18944,xx in the command mode or by using the short 
program below to input the starting address and the POKE values. 



100 INPUT "START ADDRESS" ;A 

200 INPUT "VALUE" ;B 

300 IF B=-l STOP 

400 POKE A^B 

500 A=A+1 

600 SOTO 200 



'5tar-t address for pof: 
'input value 0-255 
' terminate on ™1 
'poke to next address 
'increment ne:';:t addres 
•-'go for next value 



Using the USR(O) Call 

The 16 bjires of data comprising the short machine-language sub- 
routine are now in RAM from 18944 to 18959. How do we get to 
the subroutine from BASIC? A relevant question . . . 

The USR(x) function causes a transfer to an address somewhere 
in RAM (or ROM). The address to be used in the call must have 
been placed in locations 16526 and 16527 previous to the USR call. 
In our case, we're using a machine-language program starting at 
18944. Using standard address format, we must POKE the two bytes 
of address value 18944 into locations 16526 and 16527. Standard ad- 
dress format, as you may recall, is least significant byte followed by 
most significant byte. The code for POKEing 18944 into 16526 and 
16527 is 



1000 MS=INT(1894A/256j 
1100 LS=18944-MS*256 
1200 POKE 16526, LS 
1300 POKE 16527, MS 



' cal cu] ate ms bvte of address 
'calculate Is bvte of address 
' setup 1 s bvte for usr- 
■■ setup ms bvte for usr 
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The statement for MS finds the upper (most significant) 8 bits 
of the address, and the code for LS finds the lower (least significant) 
8 bits of the address. This scheme can be performed for any ad- 
dress value. 

The next step is actually to call the subroutine using a USR(O) 
call. If all goes well, we should call the machine-language code, 
white out the screen, and return to the next BASIC statement. 



1000 MS=INT!lB9A4/256) 

1100 LS=18944-HS»25& 

12B0 POKE li!>526.LS 

1300 POKE 16527, MS 

1400 A=USR<0) 

1500 CLS 

1600 PRINT "HOORAY" 



calculate nts b 
calculate Is byte of 
=.etuF- Is. byte for us 
setup ms bYte for us 
call machirte-lan9uag 
clear screen 
cheers 



of address 
of address 



Did it work? ( Guard, get the name of that reader who never runs 
these routines. Better use a larger pad of paper . . .) If you speci- 
fied a memory size of 18944, POKEd the data correctly (or loaded 
a SYSTEM tape), and then used the program above, you will have 
seen a rapid flash of white before your eyes similar to the one you 
saw after writing out a check for a TRS-80 system. Did you time it? 
The time to white out the screen in this case was about 1/25 of a 
second, about 20 times faster than the fastest string graphics method! 

Any Arguments? 

The format of the USR(O) call set a variable (A) equal to the 
USR call. The within the function was a dummy argument. The 
USR call provides for use of a real argument if the user desires. The 
value or variable within the parentheses will then be passed to the 
machine-language subroutine. Upon return, an argument will be 
passed back by setting the specified variable (in this case, A) equal 
to the argument to be returned. 

What is the purpose of passing arguments back and forth? The 
obvious answer is that machine-language subroutines may require 
operands just as BASIC subroutines require operands. Let's illustrate 
how an argument is passed to a machine-language subroutine. Sup- 
pose that we require a subroutine to delete a character on the screen 
for word processing, sometimes called "text editing." Word process- 
ing enables us to construct text representing form letters, book manu- 
scripts, or other text-related material. The deletion will cause the re- 
maining text to "snake up." The character position (0-1023) of the 
character to be deleted will be passed to the machine-language sub- 
routine, which will delete the character and snake up the remaining 
text on the screen. The code for this machine-language function is 
shown below. 
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0800 


CD7F0A 


00100 DELETE 


CALL 


2687 


;SET CURSOR POSITION 


0003 


E5 


00110 


PUSH 


HL 


;FOR TRANSFER 


00B4 


Dl 


00120 


POP 


DE 


;NOW IN DE 


0005 


210004 


00130 


LD 


HL. 1024 


;FOR IK SCREEN 


0008 


B7 


00140 


OR 


A 


! CLEAR CARRY 


0009 


EDS 2 


00150 


SBC 


HLiDE 


;1024-POSITION 


000B 


E5 


00160 


PUSH 


HL 


; TRANSFER 


000C 


CI 


00170 


POP 


BC 


:T0 BC 


000D 


21003C 


00180 


LD 


HL. 15360 


; SCREEN START 


0010 


1<? 


00190 


ADD 


HLiDE 


;find position 


0011 


E5 


00200 


PUSH 


HL 


;F0R TRANSFER 


0012 


Dl 


00210 


POP 


DE 


;NOW IN DE 


0013 


23 


00220 


INC 


HL 


;FOR SOURCE 


0014 


EDB0 


00230 


LDIR 




! BLOCK MOVE 


0016 


3E20 


00240 


LD 


A, 32 


; BLANK 


0018 


32H-JF 


00250 


LD 


(16383), A 


; STORE IN LAST POSIT! 


001B 


C9 


00260 


RET 




; RETURN TO BASIC 


0000 




00270 


END 






00000 TOTAL 


ERRORS 








34754 TEXT 


AREA BYTES LEFT 








DELETE 0000 


00100 









The code above first calls a subroutine at location 2687 in ROM. 
This subroutine loads the HL register with the argument. If we 
had said 

100 A = USR(10n) 

1011 would have been the argument passed to DELETE in HL 
after we had CALLed the 2687 subroutine. Every time an argument 
is to be passed to a machine-language subroutine, the "CALL 268T' 
must be executed to load the argument into the HL registers. This is 
simply the way chosen to pass an argument between BASIC and a 
machine-language subroutine in the TRS-80. There is nothing pro- 
found about it. 

With the argument of 0-1023 representing the character position 
in HL, a PUSH and POP are performed to also transfer the argument 
to the DE registers. Next, the argiunent is subtracted from 1024 to 
give the number of bytes between the character position specified 
and the end of the screen. HL is then loaded with the actual ad- 
dress of the screen memory location by adding 15360, the start of 
the screen memory, to the character position. This value is trans- 
ferred to DE. One is then added to HL. All of this manipulation 
was necessary to set up the HL, DE, and BC registers properly so 
that a "Move Block" LDIR instruction could be executed. The LDIR 
moves all memory locations in video memory from the character po- 
sition plus one down one location to effectively delete the character 
at the specified character position and "snake up" the text. As the 
last location in the video memory had nothing to fill it, a blank is 
used for the last screen character. The machine-code data after 
assembly for this machine code is given below. It is also relocat- 
able code that could be placed anywhere in memory. 



195 



Hexadecima' CD,7F,0A,E5,D1,21,00,04,B7,ED,52,E5,C1,21,00, 

3C,19,E5,D1,23,ED,B0,3E,20,32,FF,3F,C9 
Decimal r— 205.127,10,229,209,33,0,4,183,237.82,229,193,33, 

I 0,60,25,229,209,35,237,176,62,32,50,255,63,201 , 

18944 '^'^' 

POKE the machine code above from 18944 through 18971 us- 
ing the POKE program shown previously. Of course, once again, 
MEMORY must have been set to 18944 before the POKEs. You can 
optionally assemble this code and load a SYSTEM tape. If you do, 
enter the following source line before assembly: 
00090 ORG 18944 

We now have the machine-language program in RAM ready to 
be called by a BASIC "driver." For the driver, we'll use a routine 
to fill the screen with simulated text. The routine will then ask for 
the character position to be deleted, and delete the indicated char- 
acter. 



2000 CLS 

?010 INPUT "CHARACTER POSITION=";B 

2020 tl- B<a OR B>1023 SOTO 2010 

2030 FOR 1=15360 TO 16383 

2040 A=RND(6) 

2050 IF A<'>1 SOTO 20B0 

2060 A=32 

2070 GOTO 2100 

2080 A=RND(70) 

2070 IF A<65 SOTO 2080 

2100 POKE I. A 

2110 NEXT I 

2120 MS=INT< 1B944/256) 

2130 LS=18944-MS»256 

2140 POKE 16526. LB 

2150 POKE 16527, MS 

2160 AS=INKEY* 

2170 IF AS="" GOTO 2160 

21B0 A=UaR(B) 

2190 GOTO 2160 



ear- screen 

tput position for delete 
?st for- valid position 
■'setup loop for screen niemor-, 

'random** for space 

'go if not space 

' put ujord space ever-.' 6th 

' go to fill screen 

'get alpha character 

' throiL' out less than a 

' store in screen 
■' loop for Ik 
5t ms address bvte 
E-t Is address byte 
tore 1 s for usr cat 1 
tor-e ms for usr cal 1 
-'test keyboard input 
-' 1 OOP 1 f none 

'pass delete position 

'delete at same position 



The driver first clears the screen and asks for the character po- 
sition for the delete. After a valid character position is input, the 
screen memory is filled with random text characters including spaces 
to simulate actual text. (A space is generated every five characters 
or so by the A = RND(6) logic.) After the screen is filled, the stan- 
dard POKE of the machine-language subroutine is made at 16526 
and 16527. At the next key depression, the machine-language sub- 
routine at 18944 is called by A = USR(B). B is the character posi- 
tion previously input (0-1023). For every subsequent key depres- 
sion, another character at the same character position is deleted as 
the text snakes up. The important points in this example are: 

1. An argument was passed to the machine-language subroutine 
by USR(B). 

2. The machine-language subroutine picked up the argument by 
a "CALL 2687." 
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Before we get on to a clever way to embed machine code in 
BASIC statements, let's cover two more topics about argument pass- 
ing—passing arguments from the machine-language subroutine back 
to the BASIC program and passing multiple arguments. 

Getting an Argument Back 

Suppose that we continue with our word-processing analogy and 
create a machine-language subroutine to count the number of words 
on the screen. If a word is defined as a string of characters bracketed 
by spaces, we can easily count the words by counting the number 
of spaces. The machine-language routine will scan video-display 
memory and count the spaces, returning the word count as a vari- 
able. The assembly-language code for this is below. 



0000 


11003C 


00100 


COUNT 


LD 


DE: 15360 


0003 


010004 


00110 




LD 


EC, 1024 


0006 


210000 


00120 




LD 


HL^B 


0009 


lA 


00130 


LOOP 


LD 


A, (DE) 


000A 


FE20 


00140 




CP 


32 


000C 


2001 


00150 




JR 


NZ.CONT 


000E 


23 


00160 




INC 


HL 


000F 


08 


00170 


CONT 


DEC 


BC 


0010 


13 


001 SB 




INC 


DE 


0011 


79 


00190 




LD 


A,C 


0012 


B0 


00200 




OR 


B 


0013 


20F4 


00210 




JR 


NZiLOOP 


0015 


C39A0A 


00220 




JP 


2714 


0000 




00230 




END 




B0B00 TOTAL 


ERRORS 








34749 TEXT 


AREA BYTES LEFT 






CONT 


000F 


00170 


B0150 






COUNl 


0000 


00100 








LOOP 


0009 


0013B 


00210 







; START OF SCREEN 

■ IK CHARACTERS ON SCREEN 

; INITIALIZE SPACE COUNT 

;GET CHARACTER 

:TEST FOR SPACE 

!G0 IF NOT SPACE 

;BUMP SPACE COUNT 

; DECREMENT LOOP COUNTER 

;BUMP LOCATION POINTER 

;SET LS OF LOOP COUNT 

; MERGE MS OF LOOP CNT 

;S0 IF NOT IK 

;D0NE, RETURN TO BASIC PROS 



The code above first loads the DE register with the start of the 
screen memory and the BC register with 1024, the number of lo- 
cations to scan. HL is initiahzed to zero for the count. The code 
loops through "LOOP" to "JR NZ,LOOP" comparing each video 
display memory character with a space, ASCII 32. If a space is 
found, the count in HL is bumped by one. Each time through the 
loop, the address of the next memory location is incremented by 
one (INC DE), and the number of locations left is decremented by 
one (DEC BC). If the number of locations left in BC is not zero, 
another pass through the loop is made. At the end of the loop, HL 
contains the count of the number of spaces or words. The last action 
is to execute a jump (JP) to location 2714. This transfers the count 
in HL to the variable in the USR call. This is the "standard" way 
to pass an argument back to a BASIC routine in the TRS-80. Note 
that a "Return" (RET) instruction is not done in this case. 
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The machine code for this subroutine is shown below. POKE the 
values after first setting memory size to 18944. This code, as were 
the other two routines, is relocatable and can be placed anywhere in 
memory. Optionally, you can assemble this code with the Editor/ 
Assembler and load the resulting SYSTEM tape. If you do, add the 
following source line before assembly: 

00090 ORG 18944 

Hexadecimal 1 1,Oa3C,01,00,04,21,00,00,lA,FE,20,20,01,23, 

OB,13,79,B0,2O,M,C3,9A,0A 
Decimol p-17,0,60,1,0,4,33,0,0,26,254,32,32,1,35,1 1,19, 
I 121,176,32,244,195,154,10 
18944 

The BASIC driver for this subroutine fills the screen with simu- 
lated text characters as before, except that it ensures that only one 
space at a time is used. The number of spaces (words) is returned 
in variable A and printed. 



300B CLS 

30 !0 FOR 1=15360 TO 16383 

3020 A=RND(6) 

3030 IF AOl 60T0 3070 

3040 POKE Ii32 

3050 1=1+1 

3060 IF 1 = 16384 GOTO 3110 

3070 A=RND(90) 

3BB0 IF A<65 GOTO 307B 

3090 POKE I. A 

3100 NEXT I 

3110 MS=INT( 18944/256) 

3120 LS=18944-MS»256 

3130 POKE 16526. LS 

3140 POKE 16527. MS 

315B A=USR<0) 

3160 CLS 

3170 PRINT "NUMBER OF WORDS IS 



'clear screen 

■'setup loop for screen 
'get # for space 
'if not space continue 
'poke space 

'bump character- position 
'go if screen fill done 
'get non-space character 
'ignore control codes 
'poke alphabetic 
"'loop to fill screen 

'get ms of address 

'get Is of address 

' poke for usr cal 1 

' poke for usr cal 1 

'call uiord count routine 

'clear screen 

'print number 



3180 IF INKEYS=-" SOTO 3180 ELSE GOTO 3000 

Handling Two-Way Passing and Multiple Arguments 

The above example showed the mechanism for passing arguments 
back to the BASIC routine, and the example previous to that illus- 
trated passing an argument to the machine-language routine. In 
some cases, it is necessary to both pass an argument to the machine- 
language routine and pass one back from the machine-language sub- 
routine. An example of this might be a machine-language routine 
that scanned the display memory for a given character and then 
returned the character position of the character. In this case (we 
won't write the code), the call might be 

100 A=USR(ASC(A$)) 

where A$ was the one-character string variable and A was the re- 
turned character position 0-1023, or -1 if the character was not 
found. In the corresponding machine-language code, the first in- 
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struction would "CALL 2687" to load the HL register with ASC ( A$ ) , 
and the last instruction would be a "JP 2714" to take the character 
position in HL and store it in variable A. 



SEARCH 



CALL 2687 



;get argument 



(other code) 



JP 



2714 ;return argument 



We know from the above examples how single arguments can be 
passed between a BASIC program and a machine-language sub- 
routine, but how about multiple arguments? The HL register in the 
Z-80 is 16 bits wide and can therefore hold an integer variable. All 
arguments passed between BASIC and a machine-language subrou- 
tine must be integer variables of 16 bits or less. (We used single- 
precision arguments above that were converted by the 2687 routine 
to integer values. We also took the integer argument from the sub- 
routine and converted it to a single-precision form. As long as the 
argument is between -32768 and -f 32767, this technique is vaUd, 
although it is probably wise to use integer variables such as A% 
or B% when setting up USR calls.) 

If multiple arguments are required, it is possible to pack them 
into a 16-bit integer variable. An example of this would be use of 
a machine-language subroutine that drew a Hne from a given x,y 
point to another x,y point. The four arguments could be packed as 
shown in Figure 11-4. 



4 BITS 



4 BITS 



BYTEO 
BYTEl 



XI 



X2 

H 1— 



Yl 



Y2 



2-BYTE 
INTEGER 
VARIABLE 

XY% 



Figure 11-4. Packing arguments. 



The subroutine, of course, would have to unpack them into four 
separate arguments. The packing code is shown below and assumes 
variables XI, Yl, X2, and Y2 are the appropriate x,y values. The 
packed result passed to the machine-language subroutine is in inte- 
ger variable XY. 
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100 XY%=X1*4096 
200 A=USR(XY%) 
300 5 



i-Yl*256+X2*16+Y2 



Another method of passing as many arguments as required is 
simply to make multiple calls to the machine-language subroutine. 
On the first call, the subroutine starts counting the number of argu- 
ments and does not process the arguments until all the necessary 
arguments have been received. Typical code for this is shown below 



100 


A = USR(B%) 


'first argument 


200 


A=USR(C%) 


'second 


300 


A = USR(D%) 


'third 


400 


A=USR{E%) 


'fourth and goi 


500 


PRINT A 


'done 



A final method for passing a number of arguments is to store the 
arguments in a string. As in other examples we have seen, the string 
is a "dummy" string whose only purpose is to be filled with argu- 
ments for the machine-language subroutine. Suppose that we have 
four integer arguments to pass to the machine-language subroutine. 
We know that each integer argument requires two bytes and that 
we need, therefore, eight bytes to hold the arguments. The code 
below establishes a dummy string of eight bytes, finds the location 
of the string by VARPTR, fills in four arguments of 1000, 2000, 3000, 
and 4000, and then calls the machine-language subroutine with the 
address of the dummy string. Arguments can also be passed back 
to a BASIC program via the dummy string. 

(IS, MS are precomputed address of subroutine.) 



^,000 


A-/.= 1000 


' first argument 


6010 


B'/.=2000 


'second argument 


6020 


C-/.=3000 


'third argument 


6030 


Dy.=4000 


'fourth argument 


60A0 


A$="1234S678" 


' dumnrr strl ng 


6050 


B=VARPTR<A3i> 


'address of parameter b!f 


6060 


C=PEEK < B+2 ) *256+PEEK < B+ 1 ) 


'address of string 


6070 


POKE C,A-/. 


' store first arg 


60B0 


POKE C+2,B7. 


'store second a r 9 


6070 


POKE C+4 J CX 


'store third arg 


610B 


POKE C+6.D-/. 


'store fourth arg 


6110 


POKE 16526,LS 


'setup address 


6120 


POKE 165271 MS 


' for call 


6130 


A=USR(C) 


'cal! machine language 



Handling Multiple Machine-Language Subroutines 

Is there any reason for not having multiple machine-language sub- 
routines? None whatsoever. Just remember to POKE the address of 
the location of each new subroutine into 16526 and 16527 before the 
USR call is executed. If machine-language subroutine 1 was at 18900 
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and subroutine 2 was at 18950, for example, the code to call the two 
consecutively would be 



100 POKE 16526, lS900-INT(lB900/256)«256 

200 POKE 16527. INK 1B900/256) 

300 A=USR(0) 

«00 POKE 165261 lS950-lNT(18950/256)»256 

500 POKE 16527. lNT(ia950/256) 

600 B=USR<0) 



Arguments to each subroutine could be handled by the same meth- 
ods as we discussed above. 

A Neat Method for Embedding Machine-Language 
Subroutines in BASIC Code 

Now let's take a look at an extremely good method for using 
machine-language subroutines in BASIC programs. The idea is to 
construct a string variable by using the CHR$ function to embed 
machine-language values in the string. Then the location of the string 
is found by the VARPTR, the location is POKEd into locations 16526 
and 16527, and a USR call is executed to perform the subroutine. 
The advantage of this method is that no separate set of POKEs or 
loading of a SYSTEM tape has to be done. 

Let's use a fourth example of machine-language code to see how 
this technique works. First, we must assemble the subroutine as be- 
fore. This particular subroutine contains two subroutines, one to 
write the contents of the video display to cassette tape and the 
second to read the cassette tape back and restore the display. The 
subroutines may be called from any BASIC program that contains 
them, so it is possible to save the appearance of the screen for game 
displays, business reports, or error conditions and restore the dis- 
play at any later time. The subroutines use the machine-language 
cassette routines in Level II BASIC, so the entire process is very fast. 

The machine-language code is presented below. The ROM rou- 
tines CALLed are 212H (212 hexadecimal) (Define Cassette), 296H 
(Find Leader and Sync Byte), 235H (Read Byte), 1F8H (Turn Off 
Cassette), 287H (Write Leader and Sync Byte), and 264H (Write 
Byte). "IN" reads 1024 bytes from cassette to restore the display, 
while "OUT" writes out 1024 bytes from display memory. We can't 
go into detail on the cassette functions in this chapter, but we'll 
cover some of the code in the next chapter, "POKEing Around in 
Memory." 



0000 


AF 


00100 


IN 


XOR 


A 


;0 FOR CASSETTE 1 


0001 


CD 1202 


00110 




CALL 


212H 


; START CASSETTE 


0004 


CD9602 


00120 




CALL 


296H 


-.FIND LEADER, SYNC BYTE 


0007 


21003C 


00130 




LD 


HL.3C00H 


: START OF SCREEN 


000A 


010004 


00140 




LD 


BC, 1024 


UK BYTES IN SCREEN 


000D 


CD3502 


00150 


IN10 


CALL 


233H 


;read one byte 



201 



0010 


77 


00160 






LD 


( HL ) , A 


0011 


23 


00170 






INC 


HL 


0012 


0B 


00180 






DEC 


BC 


0013 


78 


00190 






LD 


A.B 


0014 


Bl 


00200 






OR 


C 


0015 


20F6 


00210 






JR 


NZ> IN10 


0017 


CDFB01 


00220 






CALL 


IFBH 


001A 


C9 


00230 






RET 




00 IB 


AF 


00240 


OUT 




XOR 


A 


001C 


CD 1202 


00250 






CALL 


212H 


0O1F 


CDB702 


00260 






CALL 


287H 


0022 


21003C 


00270 






LD 


HL,3C00H 


0025 


010004 


00280 






LD 


BCi 1024 


0028 


7E 


00290 


OUT 10 


LD 


A ! < HL ) 


0029 


CD6402 


00300 






CALL 


264H 


0B2C 


23 


00310 






IIMC 


HL 


002D 


0B 


00320 






DEC 


BC 


002E 


78 


00330 






LD 


A,B 


002F 


Bl 


00340 






OR 


C 


0030 


20F6 


00350 






JR 


NZ)OUT10 


0032 


CDFS01 


00360 






CALL 


1F8H 


0035 


C9 


00370 






RET 




0000 




00380 






END 




00000 TOTAL 


ERRORS 










34334 TEXT 


AREA BYTES 


LEFT 






IN 


0000 


00100 










IW10 


000D 


00150 


002 


10 






OUT 


00 IB 


00240 










OUT 10 0028 


00290 


00350 







! STORE IN SCREEN MEMORY 

; POINT TO NEXT LOCATION 

; DECREMENT BYTE COUNT 

;SET MS BYTE OF COUNT 

i MERGE LS BYTE 

;S0 IF NOT IK 

ITURN OFF CASSETTE 

; RETURN 

;0 TO A 

; START CASSETTE 

iWRITE LEADER ON TAPE 

; START OF SCREEN MEMORY 

;BYTE CNT = IK 

;SET BYTE 

;WRITE ONE BYTE 

; POINT TO NEXT 

; DECREMENT BYTE COUNT 

;SET MS BYTE OF COUNT 

; MERGE LS BYTE 

;60 IF NOT IK 

;TURN OFF CASSETTE 

; RETURN 



The machine code for the subroutines is presented below in deci- 
mal form. It's relocatable and can be used anywhere in RAM mem- 
ory. The "IN" portion starts at the first byte, and the OUT portion 
starts at the 28th byte. 

1 75,205,1 8,2,205, 1 50,2,33,0,60,1 fl,i, 
205,53,2,1 19,35,1 1,120,177,32,246,205, 
248,1 ,201 ,1 75,205,1 8,2,205,1 35,2,33,0, 
60, 1 ,0,4, 1 26,205,1 00,2,35,1 1 ,1 20,1 77,32,246, 
205,248,1,201,255 

The machine code above is converted to a string by one of two 
methods. The first uses CHR$ to assemble a striog of the codes 
above. 

100 ZA$ = CHR$(175)-|-CHR$(18)+ ... 

This method works fine, but there is a limit on the number of char- 
acters per statement line, and it's necessary to break up the string 
into several separate strings and then concatenate to get an entire 
contiguous string. 

We'll use the second method, which assembles a string by moving 
DATA values into a dummy string, similar to the graphics method 
explored earlier in the book. 

100 ZA*="THIB IS A DUMMY STRING THAT WILL BE FILLED WITH CHARACT" 
200 ZA=VARPTR(ZA*i 'find address or block 

300 ZB=PEEK(ZA+1 i+PEEK(ZA+2)»256 'find string address 
400 ZC=ZB+27 'find 2nd routine address 



500 FOR ZI=ZB TO ( ZB+LEN( ZAas )-l ) 
600 READ ZZ 
650 POKE ZI>ZZ 
700 NEXT ZI 



tup loop for pokein9 
'get bvte of ml 
' poke ml bvte 
^ ' 1 OOP ti 1 done 



202 



800 DATA 175,205,18,2,205,150,2,33,0,60,1,0,4,205,53 
900 DATA 2, 119, 35, <1, 120, 177, 32, 246, 205, 248,1, 201, 175 
1000 DATA 205,18,2,205,135,2,33,0,60,1,0,4,126,205,100 
1100 DATA 2,35,11,120,177,32,246,205,248,1,201,255 

The above code initializes the string to the machine-language val- 
ues from the DATA statement. To call the OUT machine-language 
subroutine, use the following code 

1900 POKE 16526,(ZC-(INT(ZC/256))+256 
2000 POKE 16527,(INT{ZC/256)) 
2100 A=USR{0) 

To call the IN machine-language subroutine, use the following code 

2400 POKE 16526,ZB-(INT(ZB/256))*256 
2500 POKE 1 6527,(1 NT(ZB/256)) 
2600 A=USR(0) 

The complete "driver" is shown below. It fills the screen with ran- 
dom data, dumps the screen to cassette tape, clears the screen, and 
then restores the previous screen contents. 

i^S 7A*r,ISSii4L'^ °^"""' STRING THAT WILL BE FILLED WITH CHARACT" 

200 ZA=VARPTR(ZA») ,f,n<j address of block 

300 ZB=PEEK<ZA-<-l.+PEEK<ZA+2)*256 -find -.tring addre" 

400 ZC=ZBH-27 .find 2nd routine iddre^-c. 

IZ ppL'^;'^- ™ 'ZB+LENCZAS.-l, |-. setup ,oop for Pok^ing 

600 READ ZZ .g^t brte of ml 

700 NEXT ZI "-.ig^p ^j, ^j,^^ 

800 DATA 175,205,18,2,205,150,2,33,0,60,1,0,4,205,53 

900 DATA 2,119,33,11,120,177,32,246,205,248,1,201,175 

1000 DATA 205,18,2,205,135,2,33,0,60,1,0,4,126,205,100 

1100 DATA 2,35,11,120,177,32,246,205,248,1,201,255 

1200 O-S -clear screen 

1250 INPUT "READY CASSETTE, PRESS ENTER" ;A$ 

1300 FOR 1=15360 TO 16383 p'setuP for screen fill 

1400 A=RND(191) 

1500 IF A<32 GOTO 1400 

160B POKE 1,A 

17B0 NEXT I 

1900 POKE 16526, ZC-(INr(ZC/256) i»2S6 ' setup" addre^""" 

2000 POKE 16527, (INT(ZC/256i) 'second bvte 

2100 A=USR(B) -call routine to dumP screen 

.^200 INPUT "READY CASSETTE, PRESS ENTER" ; A* 



'get character 1-191 
"ignore control codes 
'fill screen 

loop til done 



2300 CLS 



'clear screen 



24B0 POKE 16526, ZB-( INT< ZB/256) )«256 'setup addre" 

2300 POKE 16527, (INT < ZB/256 ) 1 '«econd bvte 

26B0 A=UBR(0) -call routine to read screen 

2700 INPUT "AGAIN" ;A« 'continue if desired 

2800 GOTO 120B 'loop 

This concludes our discussion of assembly and machine-language 
interfacing. We hope you haven't been frightened away, but rather 
that you see the potential for interfacing short machine-language 
routines in your BASIC programs for "time-criticar processing such 
as asplay work and cassette use. In the next chapter, we'll be look- 
ing at further machine-language topics when we discover some of 
the deep, dark secrets of Level II BASIC in ROM. 
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CHAPTIR 12 



POKEing Around in Memory 



Are you one of those people who likes to find out how things work? 
Do you like to take apart grandfather clocks, threshing machines, 
and Boeing 747s? If so, you may be able to make BIG MONEY in 
Level II Computer Programming. Since we can't put this advei-tise- 
ment on a matchbook cover, we'll have to include it here, a logical 
place, since this chapter will reveal how (to a pertain extent) Level 
II BASIC functions. Although we can't provide a complete theory of 
operation even in several pages, we can at least point out some of 
the high points, such as statement format, variable and string stor- 
age, device control blocks (DCBs), keyboard and cassette operation, 
and some ROM assembly-language calls. Some of these items may 
be used to great advantage in doing interesting things; others are 
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merely tutorial. We must caution you, however— if you tamper with 
the "internals" of a system such as Level II, you must be prepared 
to take the consequences if your experimentation doesn't turn out. 
Ready, Dr. Frankenstein? . . . 

An Approach to PEEKing 

First of all, we know that Level II BASIC is written in Z-80 ma- 
machine code and that it occupies roughly ROM locations through 
12287, the first 12K of the 16K addresses dedicated to ROM and 
system addresses (see Figure 11-2). If we know Z-80 assembly lan- 
guage, one way to decode how the interpreter works would be to 
PEEK at locations on up and convert the data found there into 
the equivalent Z-80 instructions. We could then sit down at our 
leisure and follow these instructions to outline Level II BASIC 
operation.^ To do this, however, we must be fairly adept at "read- 
ing code." At times, even experienced programmers have trouble 
reading their own programs six months after they've written them. 

The above approach is possible, however, and certainly has been 
performed. Rather than hand translating each value found, various 
Z-80 disassemblers are available that will automatically disassemble 
values into the corresponding Z-80 mnemonics. As a matter of fact, 
such a disassembler may be constructed using a BASIC program! 
The approach here is to get a value from memory, decode the "op- 
eration code" and operands, and print out the memory location, 
op code mnemonic, and operands. A typical printout of such a dis- 
assembler is shown in Figure 12-1. 

We'll assume that you're not as conversant with Z-80 assembly 
language as you could be and take another approach. Interspersed 
with the assembly-language instructions in BASIC are sets of 
ASCII data. Error messages and other types of messages are in 
ASCII code, for example. Another ASCII-encoded set of data con- 
sists of the BASIC program statements themselves. If we PEEK and 
display in ASCII, we should be able to see all kinds of interesting 
things appear on the display as we scan through memory, ROM and 
RAM. Let's give it a try. The following program scans memory start- 
ing at a given location and continuing for 32K locations. 



1B0 


T=0 


' ini t lal ise f 1 ag 


110 


CLS 


'clear screen 


120 


INPUT "START ADDRESS" ;B 


'irtput start address 


130 


INPUT "ASCII ONLY Y/N";C* 


'give choice of data 


140 


FOR I=B TO 32767 


—'scan up to 32k 


150 


A=PEEK<I ) 


'peek current location 


160 


IF A<32 OR A>9a GOTO 210 


' 9 o 1 f n 1 a s c 1 1 


170 


IF T=0 PRINT I!»/";CHRS(A) 


;ELSE PRINT CHR$<A); 


180 


T=l 


j 'set location flag 
'get next location 


190 


NEXT I 


200 


STOP 


'stop at end of scan 


210 


IF T=l PRINT 


i 'if numeric) i f 


220 


T=0 


I 'reset locn flag 


230 


IF C$="N» PRINT I;"/";A 


i 'print locn^data 


240 


NEXT 1 


■—'get next location 
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aaea 

0BIZ11 
Q0B2 
(3003 
013138 
00I3B 

aaac 

13000 

13010 

0013 

B014 

0016 

0018 

001B 

B01C 

001E 

0020 

0023 

0024 

0026 

002B 

0B2B 

0O2E 

0030 

0033 

8036 

0038 

0B3B 

B03E 

0040 

0043 

0044 

0045 

0046 

0049 

0B4C 

004D 

B04E 

0050 

0051 

0052 

0053 

0054 

0057 

0058 

0059 

005A 

005B 

a05D 

003E 

0060 

0061 

0062 

0063 

0065 

0066 

0069 

006C 

0B6D 

0B6F 



F3 

AF 

C37406 

C30040 

C30040 

El 

E9 

C39F06 

C30340 

C5 

0601 

1B2E 

C3O640 

C5 

0602 

1826 

C3O940 

C5 

0604 

181E 

C30C40 

111540 

18E3 

C30F40 

111D40 

18E3 

C31240 

112540 

IBDB 

C3D905 

C9 

00 



C3C203 

CD2B0O 

B7 

C0 

iaF9 

0D 

OD 

IF 

IF 

01015B 

IB 

0A 

lA 

08 

1809 

19 

2020 

0B 

78 

Bl 

20FB 

C9 

310006 

3AEC37 

3C 

FE02 

D20000 



DI 

XOR 

JP 

JP 

JP 

POP 

JP 

JP 

JP 

PUSH 

LD 

JR 

JP 

PUSH 

LD 

JR 

JP 

PUSH 

LD 

JR 

JP 

LD 

JR 

JP 

LD 

JR 

JP 

LD 

JR 

JP 

RET 

NOP 

NOP 

JP 

CALL 

OR 

RET 

JR 

DEC 

DEC 

RRA 

RRA 

LD 

DEC 

LD 

LD 

EX 

JR 

ADD 

JR 

DEC 

LD 

OR 

JR 

RET 

LD 

LD 

INC 

CP 

JP 



A 

0674H 

4O00H 

40BOH 

HL 

(HL) 

069FH 

4003H 

BC 

B.01H 

0B46H 

4B06H 

BC 

B>02H 

0046H 

4009H 

BC 

B,04H 

0046H 

400 CH 

DEi4B15H 

B013H 

400FH 

DEI401DH 

001 BH 

401 2H 

DEi4B25H 

001BH 

05D9H 



B3C2H 

002BH 

A 

NZ 

0049H 

C 

C 



BCiSBOlH 

DE 

A. (BC) 

Ai (DE) 

AFiAF' 

0066H 

HL.DE 

NZiOBBOH 



BC 
AiB 



NZ>0O60H 

SPJ0600H 

Ai (37ECH) 

A 

02H 

NC.O0B0H 



Figure 12-1. Typical disassembly 
of a BASIC interpreter. 



The code on page 205 displays numeric and ASCII data or only 
ASCII data as requested by the user. Let's use it to display ASCII 
data only, starting at location 0. Use the "SHIFT @" keys to stop 
the display at any time; continue by hitting any key. 

Some of the first ASCII data displayed consists of single "@" and 
other characters. This simply means that some of the values stored 
in ROM as instructions are also valid ASCII characters. Location 
102, for example, is an ASCII "1" (49) vs^hlch is also the operation 
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code for an "LD SP" assembly-language instruction. The point is that 
even though data displays as an ASCII character, we can't be cer- 
tain that it doesn't represent other data. We can be (fairly) certain, 
however, that the string of ASCII at locations 261, "MEMORY 
SIZE", and 273, "RADIO SHACK LEVEL II BASIC" are the mes- 
sages printed out at the start of Level II BASIC. Let's continue . . . 
The next interesting display starts at location 5713. The ASCII 
data here is shown in Figure 12-2 and looks suspiciously like BASIC 
statement words without the first letter. Let's record that location 
as an interesting spot and continue. 





Figure 12-2. ASCII data in memory. 




The next group of meaningful data is at location 6345. The string 
is "NFSNRGODFCOVO . . . DL3". These are the Level II error 
codes arranged in order of their code numbers. Continuing, location 
6441 has the "READY" message, and 8568 has the "?REDO" mes- 
sage among others. The area from 12288 to 16383 may be skipped, 
as this is the area dedicated to device addresses (no memory) or 
video-display memory. 

From 16384, we start to get very interesting displays. They seem to 
contain portions of our program statements, but are not intact. For 
example, ""INPUT START ADDRESS";B" is stored as ""START 
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ADDRESS";B." Other lines are stored in similar fashion. Let's stop 
at this point'and investigate what's happening to our nice text input. 

BASIC Statement Format 

Let's take a look at the statement "120 INPUT"START AD- 
DRESS";B." First, find the start of ""START ADDRESS";B." It 
should be close to 17129. Having found it, run the program starting 
from about 5 locations before, Hsting both ASCII and numeric data. 
For example, if " "START ADDRESS";B" was at 17148, Hst 17143 on. 
A typical display of this line would look like 

17143/21 

17144/C 

17145/120 

17146/0 

17147/137 

17148/"START ADDRESS";B 

What is the format of the line here? " "START ADDRESS";B" 
is recognizable, but where is the "INPUT" portion? By experimen- 
tation, one could soon find the format of BASIC statement lines. 
We 11 save you the midnight hours, though, and let you refer to 
Figure 12-3, which shows the format. 

BASIC statement lines start at location 17129. Each BASIC state- 
ment line is made up of a line pointer to the next line (2 bytes), the 
line number of the BASIC statement line, the text of the hne in 
ASCII and token format, and a to mark the end of the line. (For 



BYTE 
2 . 



LAST 



NEXT LINE 
POINTER 



THIS LINE 
NUMBER 



TEXT IN ASCII AND TOKENS 



Figure 12-3. BASIC line fonnat. 



NEXT THIS 



LINE 
PNTR 



LINE 
(UMBER 



17500 17900 100 



TEXT FOR LINE 100 






18000 



18040 120 



TEXT FOR LINE 120 



17900 18000 110 



TEXT FOR LINE 110 



18040 18200 130 



TEXT FOR LINE 130 




Figure 12-4. Linked BASIC lines. 
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those who read Chapter 7, this format is known as a "single-ended 
linked list.") This means that a BASIC program may consist of 
lines that are not in physical order, as shown in Figure 12-4. This 
arrangement permits easy editing of BASIC programs. 

To see how a BASIC program is stored, we'll use a BASIC pro- 
gram to brack itself. The program below hsts the line formats of 
itself by following the "thread" of the linked lines starting with the 
Mne at location 17129. 

1000 CLS 'clc-ar screen 

H00 NL=17129 -set to first BASIC line 

1200 PRINTiPRINT 'skip tu,-, 1 ine« 

1300 PRINT "LINE AT ";NL;":> 'print location 

1400 PRINT »NL POINTERS" ;PEEK<NL)+PEEK<NL+li»256 

1500 IF PEEK (NL)+PEEK(NL+1 .1*256=0 SOTO 2400 

1600 PRINT "LINE »=" ;PEEK(NL+2)+PEEK(NL+3)«256 

1700 PRINT "TEXT FOLLOWS" 

1S00 FOR I=NL+4 TO NL+255 r' setup loop for chars 

1900 IF PEEK(I)=0 SOTO 2200 ( 'go if line end 

2000 IF PEEK(I)<32 OR PEEK(I)>90 PRINT " /" ; PEEK< I ) ; " /" ;ELSE PRINT CHR$< PEEK( I ) ) 

2100 NEXT I I-, ,^,,.,p 

2200 NL=PEEK(NL)+PEEK(NL+1 )»256 'get next line address 

2300 IF INKEY*="" GOTO 2300 ELSE GOTO 1200 

2400 PRINT "END OF PROGRAM" 'end 

Run the above program, and observe how the lines are linked 
and the content of each of the hues. Numeric data is bracketed 
by slashes ("/"), while ASCII data is simply printed out. The last 
line of any program is a dummy line whose next line pointer is 
equal to 0. 

Within the text of every Hne are numeric values called tokens 
that represent statement types. Why is this done? Using tokens 
drastically shortens the storage of program lines. Storing a 178 value 
in place of a "PRINT," for example, saves four bytes. Since many 
lines have multiple statements, it is easy to see how a 25% reduc- 
tion or more in storage requirements could result. 

The token codes may be hsted easily if we recall that one of the 
mysterious areas that we saw earher in our ASCII display was at 
5713. The area from 5712 on is a table of tokens that can be hsted 
by the following code. 

100 CLS 'clear screen 

200 N=128 'initialise token * 

300 FOR 1=5712 TO 6175 p ' setup loop for table 

400 A=PEEK(I) I 'get value from table 

500 IF A>127 PRINT CHR*(10)!N!" "SCHRSCA AND 127): ELSE PRINT CHR$(A); 

600 IF A>127 THEN N=N+1 I 'bump # if start 

700 NEXT I I- 'loop for next tolien 

For your convenience, the tokens are also listed in Table 12-1. 
The first character of every token in the table has the most signifi- 
cant bit set to delimit each statement character string from the next, 
since they are "variable length." This table also includes Disk BASIC 
tokens that are not accessible in Level II BASIC. The token table 
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Table 12-1. Level H BASIC Tokens 



128 END 


169 NAME 


210 AND 


129 FOR 


170 KILL 


211 OR 


130 RESET 


171 LSET 


212 > 


131 SET 


172 RSET 


213 = 


132 as 


173 SAVE 


214 < 


133 CAAD 


174 SYSTEM 


215 SGN 


134 RANDOM 


175 LPRINT 


216 INT 


135 NEXT 


176 DEF 


217 ABS 


136 DATA 


177 POKE 


218 FRE 


137 INPUT 


178 PRINT 


219 INP 


138 DIM 


179 CONT 


220 POS 


139 READ 


180 LIST 


221 SQR 


140 LET 


181 LLIST 


222 RND 


141 GOTO 


182 DELETE 


223 LOG 


142 RUN 


183 AUTO 


224 EXP 


143 IF 


184 CLEAR 


225 COS 


144 RESTORE 


185 CLOAD 


226 SIN 


145 GOSUB 


186 CSAVE 


227 TAN 


146 RETURN 


187 NEW 


228 ATN 


147 REM 


188 TAB( 


229 PEEK 


148 STOP 


189 TO 


230 CVI 


149 ELSE 


190 FN 


231 CVS 


150 TRON 


191 USING 


232 CVD 


151 TROFF 


192 VARPTR 


233 EOF 


152 DEFSTR 


193 USR 


234 LOC 


153 DEFINT 


194 ERL 


235 LOF 


154 DEFSNG 


195 ERR 


236 MKI$ 


155 DEFDBL 


196 STRINGS 


237 MKS$ 


156 LINE 


197 INSTR 


238 MKD$ 


157 EDIT 


198 POINT 


239 CINT 


158 ERROR 


199 TIME$ 


240 CSNG 


159 RESUME 


200 MEM 


241 CDBL 


160 OUT 


201 INKEY$ 


242 FIX 


161 ON 


202 THEN 


243 LEN 


162 OPEN 


203 NOT 


244 STR$ 


163 FIELD 


204 STEP 


245 VAL 


164 GET 


205 + 


246 ASC 


165 PUT 


206 - 


247 CHR$ 


166 CLOSE 


207 * 


248 LER$ 


167 LOAD 


208 / 


249 RIGHT! 


168 MERGE 


209 t 


250 MID$ 



is used in conjunction with a table of routine addresses starting at 
6178. This table has a two-byte address for each processing routine, 
arranged in the same order as the token table. The address for FOR, 
for example, would be found at the second location in the table 
(6180/6181). The addresses may be found by the usual PEEK(N) 
+PEEK(N+1)'256. 

Knowing the structure of BASIC statement lines can be very help- 
ful when you're designing programs to process BASIC programs 
themselves. Such things as appending two programs, merging two 
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or more programs, compiling lists of the variables used in a program, 
renumbering programs, and other utiKty functions are all possible 
when we know the structure of Level II BASIC operations. 

Suppose that we want to detect all occurrences of the REM state- 
ment in a program, for example. We may wish to leave REMarks 
in while we're debugging a program, but to delete all REMarks 
automatically after the final version of the program has been pro- 
duced. (If there ever is a final version!). The first step in this pro- 
cess would be to scan each statement line for REM tokens. The 
code below does exactly that and lists all line numbers containing 
a REM token. 

1000 CLS 'clear screen 

1010 PRINT -REMARKS AT LINES:" 'title 

1020 NL=17129 'first BASIC line 

1030 REM FIND NEXT LINE # ' remarl: for te't 

1040 A=PEEK<NL)+PEEK(NL+1)»256 

1050 REM FIND STATEMENT LINE « 

1060 8=PEEK<NL+2)+PEEK(NL+3)»256 

1070 REM IF NEXT LINE IS ZERO, DONE 

1080 IF A=0 SOTO 1200 

1090 REM BYPASS NXT LINEiST # 

1100 NL=NL+4 

1110 C=PEEK<NL) 

1120 REM IF C=0 END OF LINE 

1130 IF C=0 GOTO 1180 

1140 IF C=147 PRINT B 

1150 NL=NL+1 

1160 GOTO 1110 

1170 REM SET NEXT LINE « 

1180 NL=A 

1190 SOTO 1040 

1200 PRINT "DONE" 'must be done 



'find address of next line 
'another rem for test 
'get current line # 
'third remark 
' g.o if end of program 

'point to text and tokens 
-'get text bYte 

a remarkable program 

9o If end of 1 ine 

if remark token pr line tt 

Point to next text byte 
^'peek at next line 
last remark 

from start of 1 ine processing 
90 to process line 



The Search for Variables 

Continuing with our investigative analysis of Level II . . . We've 
seen how BASIC lines are stored, and we've looked at the token 
format. Let's next see if we can deduce something about variables 
and arrays. We know from our work with VARPTR that we can 
easily find the location of a simple variable. If we have two variables, 
A and B, for example, we can print their locations by 

2000 CLS 'clear screen 

2100 A"/.=333 'dummy variable 

2200 B'/.=666 'another dummy 

2300 LA=VARPTR(AX) 'get first location 

2400 LB=VARPTR(B7.) 'get second location 

2500 PRINT "LOCATION OF A=" ;LAi "VALUE OF A=" ; (PEEK(LA)+PEEK<LA+1 )»256) 

2600 PRINT "LOCATION OF B=" ;LB> "VALUE OF B=" ! ( PEEK(LB)+PEEK(LB+1 )*256) 

Using a technique such as the above, we can easily trace simple 
variables as they are assembled in RAM. We can also use the same 
technique on array variables. VARPTR wiU also find the location 
of the elements of an array, as shown in the code below, which 
prints out all 34 locations of A(0) through A (33). It can be seen 
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that all array locations are contiguous-that is, in a block— and the 
first element is first in the block followed by the second, 

3000 DIM A<34) 'dummv arrar 



3100 FOR 1=0 TO 33 
3200 B=VARPTR(A(I) ) 
3300 PRINT B 



5 1 u p loop for location 
'find locns of elements 
'print locations 



3400 NEXT I lOoP 

and so forth ( Guard, arrest that reader for rtmking that snide remark 
about simple writers! ) . 

What is the layout for multi-dimensional arrays? By means simi- 
lar to the above, we can find out that multi-dimensional arrays build 
data as shown in Figure 12-5. The code to illustrate the memory 
arrangement for two dimensions is shown below. 



4000 DEFINT A 'define integer 

4100 DIM A(2>2) 'establish 2-d arrav 

4200 FOR J=0 TO 2 p'loop for one dimension 

4300 FOR 1=0 TO 2 I r'looP ^"^ second 

4400 PRINT "I, J=" -.3 ;". » !J, "VARPTR=" ! (VARPTR<A(li J) 1 1 

4500 NEXT I 1 ^'continue 

4600 NEXT J "-'continue for first 

Arrays are built directly below simple variables. Knowing the 
array structure makes possible such things as creating machine- 
language subroutines to perform a "super-fast" sort or search of 
data in arrays or to perform high-speed matrix conversions. 

String variables have been discussed in Chapter 3. VARPTR can 
be used to find the location of any string. The argument returned 
for VARPTR ("string") points to a thi-ee-byte block containing the 
string length and the two bytes of the string location. Strings are 
located in one of two areas, either the string space area above the 
stack but below the MEMORY SIZE? reserved area, or in the 
BASIC statement line itself. As we saw in the graphics chapter, a 
simple sti-ing of the form A$="THIS IS A STRING" will have an 
address equal to its statement line location. A string assembled from 
concatenation, CHR$, or other methods will be in the "dynamic" 
string area. 

Houston, We're Going to Change the DCBs on 
Our TRS-80 Before the EVA . . . 

Ah, acronyms and abbreviations! Would any computer system be 
a ti-ue system without them? A DCB is a Device Control Block, and 
any TRS-80 BASIC programmer subsequently caught using the full 
name will be stripped of his number 2 pencils and display work- 
sheets. In many computer systems, it is convenient to group param- 
eters relating to an input/ output de-vice in a single block. One of 
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the reasons for this is to enable a logical device to be easily changed 
to a physical device. Suppose that in our TRS-80 system we normally 
print out on the logical PR device or printer output device. The ac- 
tual physical device associated vi'ith the logical printing function 
may be a Quick Printer I. If our installation also has Baudot tele- 



TWO-DIMENSIONAL 
DIM A(3,3) 





0.0 


1,0 


INCREASING 


2,0 


MEMORY 


3,0 


LOCATIONS 


0,1 




1.1 




2,1 




3,1 




0.2 




1,2 




2,2 




3,2 




0,3 




1,3 




2.3 




3.3 



THREE-DIMENSIONAL 
DIM A(2,2,2) 





0.0,0 


1,0,0 


INCREASING 


2.0.0 


MEMORY 


0.1,0 


LOCATIONS 


1,1.0 




2,1,0 




0,2,0 




1,2,0 




2,2,0 




0,0.1 




1,0.1 




2,0.1 




0,1.1 




1,1,1 




2,1,1 




0,2,1 



1,2,1 



2.2,1 



0,0.2 



1.0,2 



2.0.2 



0,1.2 



1,1,2 



2,1,2 



0,2,2 



1,2,2 



2.2.2 



MULTI-DIMENSIONAL 
ARRAYS 

DIM Ad.J.K.L . .R) 

\ 
THIS DIMENSION CHANGES 
LEAST RAPIDLY 




THIS DIMENSION CHANGES 
NEXT FASTEST 

THIS DIMENSION CHANGES 
"FASTEST" IN RESPECT TO 
INCREASING MEMORY LOCATIONS 

Figure 12-5. Multi-dimensional array formats. 



typewriter, we can quickly substitute this device for the Quick 
Printer I by changing some variables in the PR DCB. The alterna- 
tive to this would be to change all instructions associated with print- 
ing within the ROM instructions themselves. Since this would in- 
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volve "burning in" a new ROM, you can see that the DCB method 
is much to be preferred. 

There are three DCBs in Level II BASIC associated with the key- 
board input, video display, and line printing logical functions. The 
DCBs themselves are located in RAM at the locations shown in Fig- 
ure 12-6. Data to initialize the DCBs is moved from constants within 



DCB TYPE = 1 

DRIVER ADDRESS = 995 



16405 


1 


KEYBOARD 


227 


DCB 


3 



















"K" 




"1" 


16413 


7 


VIDEO 


88 


DISPLAY 


4 


DCB 







60 









"D" 




"0" 


16421 


6 


LINE PRINTER 


141 


DCB 


5 




67 














"P" 




"R" 



DCB TYPE = 7 

DRIVER ADDRESS = 1112 

CURSOR POSITION 



DCB TYPE = 6 

DRIVER ADDRESS = 1421 

LINES/PAGE 
LINE COUNTER 



Figure 12-6. DCBs. 

the ROM code on power-up (data for the DCBs starts at ROM lo- 
cation 1767). We can easily substitute a new keyboard input routine 
by POKEing the proper address values into locations 16406 and 
16407. Of course, the catch is that the new keyboard routine has to 
be coded in machine language and stored in RAM at the specified 
address. Similarly, we can "vector ofip' the video display and line 
printer functions into new routines by changing their addresses. 
Other parameters within the DCBs may be iuterrogated during 
BASIC program execution. We have seen one example of this in 
Chapter 4 when we examined and modified the running line count 
in the line printer DCB to effect a "top of form" action. As a fur- 
ther example of DCB use, let's change the driver address in the 
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video display DCB to enable a printout of the data on the screen. 
The following code will perform this action. 

5000 A=PEEK(16414) .get display brte 

51B0 B=PEEK<li41S) .get second display byte 

S200 C=PEEK(16422) .get Printer byte 

5300 D=PEEK( 16423) -get second printer byte 

5400 POKE 16422, A!POKE 16423, B 'put dis drvr address to 1p 

5500 POKE 16414, C:POKE 16415, D 'put Ip drvr address to disp 

After this change is made, any LIST or PRINT action will go to 
the system line printer rather than the display. A possible applica- 
tion for this is to switch between screen and line printer for pro- 
gram output without having to add "LS" for "LPRINT". The sys- 
tem can be returned to the normal configuration by swapping tihe 
two sets of addresses once more. Some characters that are valid 
for the display will not be vaHd for a Hue printer, so you may make 
the above changes at your own risk. (You can apply for ACME 
Data/ Program Insurance to protect your programs and data from 
such catastrophic risks. Insurance void in those states with stringent 
fraud laws.) 

Keyboard Kapers 

One very interesting subject that we should discuss because of its 
potential use is the keyboard operation in Level II BASIC. As you 
know, the INKEY$ function returns the string value of the keyboard 
key that has been pressed. It is possible to bypass the routine that 
does the decoding and read the keys directly. This is best done by 
a machine-language routine, but there are several interesting BASIC 
appHcations. Let's see how the keyboard functions. 

Figure 12-7 shows a simpHfied diagram of the keyboard. A row of 
keys may be read by addressing 14337, 14338, 14340, 14344, 14352, 
14368, 14400, or 14464. The value returned is dependent upon the 
column of the key pressed. Table 12-2 shows the values returned for 
addresses of various columns. Suppose we address location 14344. 
Possible values we can get back are 1 for x, 2 for y, and 4 for z. 
If more than one key is pressed simultaneously, we may also get a 
merge of several values. If we press x, y, and z together, we get a 7. 
The following code detects key press in the x, y, z row. 

100 CLS -clear screen 

200 A=PEEK< 14344) p'test x,y,2 t-ey« 

300 IF A=0 GOTO 200 l-.,^,;; ^^ nothing 

400 IF A=l PRINT "X" ELSE IF A=2 PRINT "Y" ELSE IF A=4 PRINT "Z" 

500 GOTO 200 "go for next key 

Try quickly pressing a key and holding the key down for some 
time. With a quick key press, it is possible for the BASIC routine 
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ROW 



ADDRESS = 14337 (^ Q Q Q Q (J) (J) Q 

»=0O0©0©0© 
■"0000000© 

14344 MM r Y J (V) 

©000®©©0 

00©©©©©© 



14352 



14368 



14400 



14464 SHIFT 



COLUMN VALUE; 
8 16 



1 2 4 8 16 32 

Figure 12-7. Keyboard operation. 

Table 12-2. Keyboard Decoding 



64 



128 



14337 


@/i 


A/2 


B/4 


C/8 


D/16 


E/32 


F/64 


G/128 


U338 


H/l 


1/2 


J/4 


K/8 


L/16 


AA/32 


N/64 


0/128 


14340 


P/1 


Q/2 


R/4 


S/8 


T/16 


U/32 


V/64 


W/128 


14344 


X/1 


Y/2 


1/4 












14352* 


0/1 


1/2 


2/4 


3/8 


4/16 


5/32 


6/64 


7/128 


14368* 


8/1 


9/2 


;/4 


;/8 


,/16 


-/32 


./64 


//1 28 


14400* 


ENT/1 


CLR/2 


BRK/4 


t/8 


Vl6 


■^/32 


— /64 


SP/128 


14464* 


SHFT/1 
















* Lower case 


shown on!v 

















to miss a key; it simply is not fast enough to detect a key that is 
held down for perhaps l/50th of a second. When the opposite condi- 
tion is tried, it appears to the routine that the key has been continu- 
ously pressed. Because of these limitations, "scanning" of the key- 
board is best done at a machine-language level. However, this de- 
coding scheme may be used for such things as fast game control 
where a key is simulating a real-time control, to produce a "repeat" 
function for certain keys such as cursor movement keys, or to assign 
"function" keys to keys that are not normally translated, such as 
the "SHIFT' key (the shift key produces a 1 if pressed when address 
14464 is read ) . 
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Another easy way to obtain a repeat key function is to zero the 
RAM buffer used for the keys. The btiffer is made up of seven loca- 
tions, each location corresponding to a keyboard row, as shown in 
Figure 12-8. If the location corresponding to the row in question is 
zeroed after detecting a non-null string for the INKEY$ function, 
INKEY$ will return another character if the key is still being pressed. 
Normally, INKEY$ will not return another character until the key 
is released and repressed. The code below circumvents this prob- 
lem for the X, y, and z keys, but the scheme will work for any row 
of keys by zeroing the proper buffer location. 



IB A$=INKEY$ 

20 IF A«="" GOTO 10 

30 PRINT M 

40 POKE 16441,0 

SB GOTO 10 



'get character 
'loop If null 
'print input char 
'reset buffer 
' loop 



Cassette Operations 

We saw in the last chapter how we could interface to some of the 
machine-language cassette routines. The cassette reads and writes 
data at rates of 500 baud, which represents byte (character) data 
rates of 62.5 bytes per second. Data is transferred between the Z-80 
and cassette a bit at a time; subroutines in Level II BASIC ROM 
read a bit at a time and assemble 8 bits into a byte or take a given 
byte and convert it to a stream of 8 bits for output. The byte data 
rates of 62.5 bytes per second are marginal for BASIC operation, 
and interface to the cassette routines should be done in machine 
language. The addresses for the machine-language routines for cas- 
sette operation are located as shown in Table 12-3. 

Tape operation is controlled at the most basic level by three bits, 
as shown in Figure 12-9. Two of the bits control the actual signal 
level sent to the AUX jack of the cassette tape recorder. The third 

Table 12-3. Machine-Language Cassette Routines 



Location 


Routine 


Action 


530 


Define Cassette 


Defines cassette number and turns on 
cassette. Cassette nunnber, or 1, nnusf 
be in A register before entry. 


662 


Find Leader/Sync 


Bypasses zero leader and finds sync 
byte in preparation for read. 


565 


Read Bytes 


Reads one byte from cassette. A 
register holds byte on exit. 


504 


Turn Off Cassette 


Turns off current cassette. 


647 


Write Leader/Sync 


Write zero leader and sync byte. 


612 


Write Byte 


Write byte to cassette. Byte must be in 
A register before entry. 
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16438 
16439 
16440 
16441 
16442 
16443 
16444 



@- G 
H -0 
P-W 

X-Z 
0-7 
8- / 
ENTER -SPACE 



Figure 12-8. Keyboard buffer. 



bit controls the REM(ote) jack on the cassette tape recorder. A 
fourth bit not connected with tape operation controls the 32/64 
character mode of the display. All of the four bits are controlled by 
a BASIC OUT statement. Executing an OUT with an "address" of 
255 will address the four bits of the cassette /mode select "latch." 
To see how this works, try the following code. It will turn on the 
cassette and then turn it off after a 10-second delay. 



2000 OUT 255.4 
2100 FOR 1=0 TO 4600 
2200 NEXT 3 
2300 OUT 255,0 



'turn on cassette 
j- ' for a Euhile 
^ ' 1 OOP for- delar 

'turn off cassette 



The code above sets the third bit in the cassette/ mode select latch. 
This bit controls closure of the cassette relay. 

The two bits normally used for audio outjput to the AUX input to 
the tape recorder can also operate under BASIC control. The se- 
quence to write out a pulse during machiue-language operation is 
to write a 1 (01), write a 2 (10), and then restore a "0" level by 
writing a (00). We can write out to the cassette under BASIC by 
"toggling" these two bits after first turning on the recorder. 



3000 OUT 255,4 
3100 FOR 1=0 TO 5000 
3200 OUT 255,5 
330B OUT 255,6 
3400 NEXT 1 
3500 OUT 255,0 



' turn on cassette 
p'r-ecord for a ujhile 

L' 'output one level 
'and nouj the other 
' continue 
'turn off cassette 



OUT 255, VALUE 
VALUE = 0-15 



7 


6 


5 


4 




s 


I 


) 




I 





- 


- 


- 


- 


X 


X 


X 


X 














1 

















SIGNAL 1 
SIGNAL 2 
REMOTE 
32/64 MODE 



Figure 12-9. Tape operation. 
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Although we could make a somewhat "tighter" loop by multi- 
statement lines, this is about the most efficient we can get. The re- 
sulting pulses make up a square-wave tone as shown in Figure 12-10. 
The best we can do under BASIC timing constraints is a low-pitched 
tone that sounds similar to a buzz saw. The same technique can be 
used with machine-language code to produce much higher-pitched 
tones. 



in ir> to Lo 

S if? LO irs 

CM csj csj csi 

O CD O O 



Figure 12-10. "Square-wave" output. 



rhe code above illustrates an important point. We had to set the 
REM bit (value=4) on, and we had to keep it on when we output 
values to the other two bits. Consequently, we output a 5 instead 
of a 1 ( 1 or 4) and a 6 instead of a 2 (2 or 4). 

The resulting tone produced by the code above could be fed into 
an external audio amplifier for signalling purposes. {When you hear 
the buzz saw, change the printer paper . . . . ) 

There's one bit left in the cassette/ mode select latch, the mode 
select. Turning on this bit with a 1 sets the 32-character mode, while 
turning it off sets the 64-character mode. The normal method for 
setting this mode is to execute a PRINT CHR$(23), "set 32-char- 
acter mode." Unless this method is used, the (software) display 
driver will get confused about the mode and only every other char- 
acter will be displayed. It is not recommended to turn on the mode 
select bit alone in BASIC. (If you must, PEEK at location 16445, 
OR in an 8 value, and POKE the result back to 16445 after an 
OUT 255,8.) 

Further Investigation Shows . . . 

Would you like to investigate Level II BASIC further? The first 
action to take would be to invest some time in a study of Z-80 as- 
sembly language using the Radio Shack Editor/ Assembler and TRS- 
80 Assembly-Language Programming. Then, follow the clues to the 
assembly-language routines such as the DCB driver address, the ad- 
dresses of the statement processing routines in the 6180 table, and 
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Table 124. Level 11 Processing Routine Addresses 



Location 


Procaszing 


Decimal 


Hax^dacimal 


43 


002B 


Get character from keyboard. Do not wait for 
input. On exit (A) = character or if no key 
press. 


51 


0033 


Display ASCII byte. On entry (A) = ASCII byte. 


59 


003B 


Output byte to line printer. On entry (A)=ASCII 
byte. 


73 


0049 


Get character from keyboard. Wait for input. 
On exit (A) = character in ASCII. 


96 


0060 


Timing Loop In 14.66 millisecond increments. 
On entry (BC) = Delay #. 


102 


0066 


Reset system. 


457 


01 C9 


Clear screen, home cursor. 



Table 12-5. Communication Area Addresses 







Number 




Location 


of 
Bytes 


Description 


Decimal 


Hexadecimal 


16405 


4015 


8 


Keyboard DCB 


16413 


401 D 


8 


Display DCB 


16421 


4025 


8 


Printer DCB 


16438 


4036 


7 


Keyboard Buffer 


16445 


403D 


1 


Out FF Status 


16544 


40A0 


2 


Start of String Data Pointer 


16546 


40A2 


2 


Last Executed Line Pointer 


16551 


40A7 


2 


Input Buffer Pointer 


16554 


40AA 


3 


Random Number Seed 


16607 


40DF 


2 


Default Entry Point for SYSTEAA/ 


16633 


40F9 


2 


Start of Simple Variables/End of 
Program Pointer 


16635 


40FB 


2 


Start of Arrays Pointer 


16637 


40FD 


2 


Start of Free Memory Pointer 



Others. Without detailed explanation, we'll provide some hints in 
Table 12-4 for some Level II processing routines that may be called 
in assembly language or simply in BASIC. In addition. Table 12-5 
supplies some of the interesting "Communication Area" variables 
that may be accessed for BASIC operations. 
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Index 



Absolute 

memory locations, 192 

value, 149 
Address value, 31 
Algorithm(s), 122 

sort, 128 
Allocates, 104 
And 

function, 39 

operation, 41 
Argument (s), 51, 194-197 

getting back, 197-198 

multiple, handling, 198-200 

packing, 199 

unpacking, 199 
Arrays, 21, 99, 103 

initializing, 120 

one-dimensional, 104-105 

size of, 119 

two-dimensional, 111-119 
ASCII, 44 

strings, 44-45 
Assembly-language 

coding, 187 

listing, 190 
Asterisk, blinking, 164 
ATN, 159 

AUTO command, 25 
Axes, graph, 83-84 

B 

Base, data, 133 
BASIC 

code, embedding machine-language 
subroutines in, 201-203 

DATA lists, 100-102 

statement format, 208-211 
Binary 

search, 125-128 

system, 28-30 
Bit, 30 

manipulation, 42 

sign, 33 
Blocked data, 168 
Branches, 14 
Bubble sort, 130-131 
Byte, 30 

high-order, 32 

low-order, 32 

synchronization, 161, 162 



Call, 18 
Cassette(s) 

capacity, 166-169 

files, sequential, 169-170 

operations, 217-220 

two, 170 
Catenary, 48 
CDBL, 143 
Character sets, 77 
Chessboard, 111-112 
Chips, 185-187 
CHR$ function, 51-52 
CINT, 144-145 
CLEAR command, 25 
CLOAD, 24, 160, 163 
CLOAD?, 24, 163-164 
CN, 176 
Code(s) 

control, 44 

machine-language, 190-191 

source, 191 
Columnating data, 63-65 
Columns, 62-65 
Commands, 24-25 

edit, 25-26 

tape, 160-161 
Comments, 191 
Comparison(s), 24, 48-51 
Complem?nt, 42 

two's, 33 
Concatenation, 48-51 
Constants, 20 
CONT command, 25 
Contiguous block, 104 
Control codes, 44 

Conversion, decimal-to-binary, 40-41 
Cosine, 158 
CSAVE, 24, 160, 163 
CSNG, 142-143 
Cursor(s), 54-55 

positioning, 60 

D 

Data 

base, 133 

lists, 21 

BASIC, 100-102 

print, 75-77 

structures, 99 

unordered, 121-123 
DCBs, 212-215 
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DD, 176 

Debugging, 25, 181-183 

Decimal-to-binary conversion, 40-41, 

145-147 
DELETE command, 25 
Deletion, 134, 137 
Delimit, 209 
Delta value, 98 
Device control block, 212 
Dimensions, 110-119 

three or more, 119 
Disassemblers, 205 
Displacement, 86, 109 
Distribution, 149-150, 154 
Dollar(s) 

and cents, 67-72 

signs, 70 
Double-precision variables, 20, 35-37 
Driver, BASIC, 196 

Dummy strings, string graphics usmg, 
94-95 

E 

EDIT 

command, 24 
mode, 25-26 
Editing, text, 58-61 
Elements, 104 
Entries, 108 

Equivalence operator, 24 
Error(s), 171-177 
bad file data, 177 
can't continue, 176 
data, out of, 173 
Disk BASIC command, 177 
divide by zero, 176 
illegal 

direct, 176 
function call, 173 
missing operand, 176-177 
NEXT without FOR, 173 
overflow, 174 
processing, 179-180 
redimensioned array, 176 
RETURN without GOSUB, 173 
simulating, 180-181 
string 

formula too complex, 176 
space, out of, 175 
too long, 176 
subscript out of range, 175 
syntax, 172-173 
trapping the, 177-179 
type mismatch, 176 
undefined, 172 
Exercising, 183 
EXP, 149 

Expansion Interface, 170 
Exponent, 35 



FC, 173 



FD, 177 
Field(s), 109 

specifiers, PRINT USING, 71-72 
File(s), 165 

cassette, sequential, 169-170 
Fill characters, 53 
FIX, 148 

Floating point variable, 36 
Flow, program, 11-13 
Format, statement, 11-13 
Fractions, 144-148 
Functions, 21-22, 142 

trigonometric, 155-159 



GOTO, 14 
Graphics 

mechanics of, 78-80 

method, POKE, 89-92 

review, 95 

statements, 21 

string, 92-93 

dummy strings, using, 94-95 
Graphing, general approach to, 87 
Guns versus butter, 84-87 



H 



Hypotenuse, 155 



ID, 176 
Index, 105-106 
Initializing arrays, 120 
INKEY$ function, 48-51, 215 
Input, "Universal Gee Whiz," 55-57 
INPUT#, using, 164-166 
Insert, 133-134 
Insertion, 136-137 
Instruction(s), 185-186 

repertoire, 185 

set, 185 
INT, 146, 147 
Integer variables, 20, 30-33 
Interfacing, 190 
Inteipreter, BASIC, 11 
Iteration, 126 

J 



Justification, 66-67 



K 



K, 187 
Key, 108 
Keyboard, 215-217 



Labels, 191 
Leader, 161-163 
LEFT$ function, 52-53 
Length 

fixed, 109 

variable, 109 
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Life, game of, 115-119 
Line 

printer (s), 75-77 
character set, 77 

straight, how to draw, 95-98 
Linked list, 99, 135-141 
List(s),99 

BASIC DATA, 100-102 

linked, 99, 135-141 

ordered, 123-125 
LIST command, 25 
Listing, assembly-language, 190 
LLIST command, 25, 75 
Locomotive pattern, 92-93 
LOG, 149 

Logical operators, 38-42 
Loops, 13, 19-20 
LPRINT command, 75 
LS, 176 
L3, 177 



M 

Machine language, 186 

code, 190-191 

instructions, 10 

subroutines 

embedding in BASIC code, 

201-203 
multiple, 200-201 
Mantissa, 35 

Margin, top and bottom, 76 
Memory 

layout, TRS-80, 187-190 

locations, absolute, 192 
Menus, 72-74 
Merges, 133-141 
Microprocessor, 185 
MID$ function, 52-53 
Mixed variables, 102-103 
MO, 176-177 
Modes of operation, 24 
Moving, 87-88 

N 
NEW command, 25 
NF, 173 
Not 

function, 39 

opeiation, 42, 
Number(s) 

crunchies, 22-24 

great and small, 37-38 

pseudo-random, 149-150, 151 

random, 149-154 

seed, 151 

statement, 10 
Numeric to strings, 54 

O 

OD, 173 

One-dimensional arrays, 104-105 



Opcode, 185 

Operands, 20 

Operators, logical, 38-42 

Or 

function, 39 
operation, 41-42 

Order 

ascending, 124 
descending, 124 

Ordered lists, 123-125 

OS, 175 

OV, 174 

Overflow, 141 



Packing, 166-169 
Pagination, 76 
Parentheses, number of, 172 
PEEK(s),22 

address Mmits for, 33-34 
PEEKing, 205-208 
Pixel(s), 82, 88-89 
Plotting, 83-87 

POINT command, 82-83, 88-89 
Pointers, 136 
POKE(s),22 

address, 91 

hmits for, 33-34 

graphics method, 89-92 
Positional notation, 30 
Precision 

double, 142-144 

operations, 142-144 

single, 142-144 
Print 

data, 75-77 

Statements, 20-21 
PRINT USING 

field specifiers, 71-72 

statement, 69-72 
Printers, une, 75-77 
PRINT*, using, 164-166 
Program flow, 11-13 
Prompt message, 73 
Pseudo-random numbers, 149-150, 151 

R 

Radian, 157 

RAM, 189 

Random numbers, 149-154 

READS, 102 

Records, 164 

Registers, internal, 185 

Relocatable routine, 192 

RESET command, 82-83, 87-88 

Resolution, 96 

RESTORES, 102 

RESUME statement, 178 

RG, 173 

RIGHT! function, 52-53 
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RND, 152-153 

number generator, 131 
ROM, 11, 189 
Roundoff, 148 
RUN commaDd, 24 



SD, 151-152 
Search 

binary, 125-128 

for variables, 211-212 
Seed number, 151 
Segmenting, 182 
Sequential cassette files, 169-170 
SET command, 82-83, 87-88 
Setting examples, 82-83 
SGN function, 148-149 
Shell-Metzner sort, 132 
Sign(s),70 

bit, 33 

function, 148-149 
Simulating errors, 180-181 
Simulation, 149 
Sine, 155-158 

Single-precision variables, 20, 34-35 
Skeleton, graph, 85 
SN, 172 

Snapshot, 182-183 
Sort(s) 

algorithms, 128 

bubble, 130-131 

faster, 132-133 

Shell-Metzner, 132 

two-buffer, 128 
Source code, 191 
Space, 166-169 
Speed, 166-169 
SQR, 149 

Square root function, 149 
ST, 176 
Statement(s), 10-11, 13-22 

format, 11-13 
BASIC, 208-211 

number, 10 
Storage of string variables, 46-48 
Straight line, how to draw, 95-98 
String(s) 

ASCII, 44-45 

comparison of, 51 

concatenation operator, 24 

dummy, string graphics using, 94-95 

graphics, 92-93 

dummy strings, using, 94-95 

numeric to, 54 

operations, 48-51 

statements, 20 
variables, storage of, 46-48 
STRING$ function, 53 
Structures, data, 99 



Subroutine(s), 14-19 
machine-language 

embedding in BASIC code, 

201-203 
multiple, 200-201 
Synchronization byte, 161, 162 
SYSTEM 
command, 24 
tapes, 190-193 



Tables, 99, 106-109 
TAN, 158 
Tangent, 158-159 
Tape(s) 

commands, 160-161 

SYSTEM, 190-193 
Text editing, 58-61, 194 
"Time wasters," 88 
TM, 176 
Tokens, 209 
Top of form, 76-77 
Trace option, 182 
Trapping the error, 177-179 
Trigonometric functions, 155-159 
TROFF command, 25 

TRON command, 25 
Truncated values, 87 
Truncation, 148 
Two ( s ) 

-buffer sort, 128 

complement, 33 

-dimensional arrays, 111-119 

-way passing, handling, 198-200 

U 
UL, 172 

"Universal Gee Whiz" input, 55-57 
Unordered data, 121-123 
USR(O) call, 193-194 



Value, index, 105 
Variable (s), 20 

double-precision, 35-37 

name, 11 

search for, 211-212 

single-precision, 34-35 
VARPTR, 22 

W 

Weights, 124 

Word processing, 58, 194 



Z-80, 185-186 
Zero, divide by, 176 
Zzarthians, 27-28 
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